@itpay/cli 2.1.9 → 2.1.10

package/dist/src/commands/buy.js

@@ -203,6 +203,7 @@ function buildBuyEnvelope(input) {
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: input.plan.linkOnlyURL ?? input.checkoutURL,
+        mobileUrl: input.checkoutURL,
         amount,
         plan: input.plan,
         ...(input.agentType ? { agentType: input.agentType } : {}),

package/dist/src/commands/checkout.js

@@ -22,7 +22,7 @@ export async function runCheckoutPresentation(backend, options) {
         });
         return;
     }
-    const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
+    const checkoutURL = savedCheckoutURLOrFallback(options.savedCheckoutURL, options.checkoutID, options.displayToken, checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken));
     const cardURL = localizeCardURL(absolutePublicURL(options.baseURL, presentation.card_url ?? checkoutCardURL(options.baseURL, options.checkoutID, options.displayToken)), locale);
     const qrPNGURL = absolutePublicURL(options.baseURL, presentation.card_png_url ?? presentation.qr_png_url ?? checkoutCardPNGURL(options.baseURL, options.checkoutID, options.displayToken));
     const localizedPNGURL = localizeCardURL(qrPNGURL, locale);
@@ -68,6 +68,7 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand, a
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: plan.linkOnlyURL ?? checkoutURL,
+        mobileUrl: checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),
@@ -164,6 +165,20 @@ function checkoutPageURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/checkout/${encodeURIComponent(checkoutID)}?display_token=${encodeURIComponent(displayToken)}`;
 }
+function savedCheckoutURLOrFallback(savedURL, checkoutID, displayToken, fallback) {
+    if (!savedURL) {
+        return fallback;
+    }
+    try {
+        const parsed = new URL(savedURL);
+        const belongsToCheckout = parsed.pathname === `/checkout/${checkoutID}`;
+        const sameToken = parsed.searchParams.get("display_token") === displayToken;
+        return belongsToCheckout && sameToken ? savedURL : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
 function checkoutCardURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
     return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;

package/dist/src/commands/checkout_handoff.js

@@ -17,8 +17,26 @@ export function buildWorkBuddyPresentFilesAction(url) {
         arguments: { files: [url] },
     };
 }
+function hasCompleteCheckoutTokens(url) {
+    if (!url) {
+        return false;
+    }
+    try {
+        const parsed = new URL(url);
+        return Boolean(parsed.searchParams.get("display_token") && parsed.searchParams.get("complete_exchange_token"));
+    }
+    catch {
+        return false;
+    }
+}
 export function buildCheckoutHandoff(input) {
     const handoff = { url: input.url };
+    // mobile_url is only emitted when the link carries the complete token pair;
+    // a display-token-only link cannot finish the same-device exchange after payment.
+    const mobileUrl = hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : undefined;
+    if (mobileUrl) {
+        handoff.mobile_url = mobileUrl;
+    }
     const workBuddyAction = isWorkBuddyPlainChat(input.agentType, input.platform);
     if (workBuddyAction) {
         handoff.agent_action = buildWorkBuddyPresentFilesAction(input.url);
@@ -40,27 +58,41 @@ export function buildCheckoutHandoff(input) {
     }
     return {
         handoff,
-        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount),
+        instruction: checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl)),
     };
 }
-function checkoutHandoffInstruction(agentType, platform, amount) {
+function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
-        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink
+            ? "，然后把 handoff.mobile_url 作为可点击链接发给用户，说明“手机端点开可直接跳转支付宝或微信支付；小程序内打不开时复制到手机浏览器打开即可”"
+            : "";
+        const failLinks = hasMobileLink ? "发送 handoff.url 与 handoff.mobile_url" : "发送原始 handoff.url";
+        return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}${mobileSentence}，然后停止等待。若工具失败，只${failLinks}，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (isZCodePlainChat(agentType, platform)) {
-        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink
+            ? "，并把 handoff.mobile_url 发给用户备用（手机端点开可直接跳转支付宝或微信支付）"
+            : "";
+        const fallbackLinks = hasMobileLink ? "同一个可点击 handoff.url 与 handoff.mobile_url" : "同一个可点击 handoff.url";
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}${mobileSentence}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示${fallbackLinks}。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (agentType?.trim().toLowerCase() === "doubao-work" && platform === "plain_chat") {
-        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 handoff.url 标为“手机直接打开收银台”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const directLink = hasMobileLink ? "handoff.mobile_url" : "handoff.url";
+        const directLabel = hasMobileLink ? "手机直接打开收银台（可跳转支付宝/微信）" : "手机直接打开收银台";
+        return `Backend 尚未确认付款。在当前豆包工作对话中展示两个有标签的官方入口：将 ${directLink} 标为“${directLabel}”，将 handoff.qr_image_url 标为“二维码图片（保存或用另一台设备扫码）”。说明金额 ${amount} 后停止等待。不要解析或单独输出 URL credential，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "markdown") {
-        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (platform === "terminal") {
-        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+        const mobileSentence = hasMobileLink ? "，并展示 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。在用户可见终端展示当前 Checkout 的二维码、handoff.url 和金额 ${amount}${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
     if (agentType?.trim().toLowerCase() === "openclaw" && platform === "telegram") {
-        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 handoff.qr_image_url、金额和 handoff.url，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
+        const failLinks = hasMobileLink ? "handoff.qr_image_url、金额、handoff.url 与 handoff.mobile_url" : "handoff.qr_image_url、金额和 handoff.url";
+        return `Backend 尚未确认付款或授权状态。立即使用 OpenClaw 原生 message tool，严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行；它会发送金额 ${amount}、二维码、📱 手机点这儿支付和 📋 已授权给我读。不得改写 presentation、换用其他消息工具、拆开按钮发送或用普通回复声称按钮已经发送。确认 message tool 调用成功后停止等待。收到 callback_data "itp:grant_confirmed:<checkout_id>" 时，表示用户声明已在收银台授权读取；立即执行 next.command 查询同一 Checkout，再只执行 Backend 返回的 next.command 进入同一 Execution 的 grant 流程。该 callback 不证明付款成功或 grant 已生效；Backend 未返回 grant_active 前不得读取或猜测结果。若原生 message tool 明确失败或当前 Telegram 未启用 inline buttons，只发送现有 ${failLinks}，报告按钮不可用并停止；不要创建新的 Checkout、Payment Intent 或 Execution。`;
     }
-    return `Backend 尚未确认付款。把 handoff.url 和可用的 handoff.qr_image_url 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    const urlList = hasMobileLink ? "handoff.url、handoff.mobile_url（手机端点击直达支付）和可用的 handoff.qr_image_url" : "handoff.url 和可用的 handoff.qr_image_url";
+    return `Backend 尚未确认付款。把 ${urlList} 实际发送到当前会话，说明金额 ${amount}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
 }

package/dist/src/commands/services.js

@@ -1500,6 +1500,7 @@ function buildServicesCheckoutEnvelope(response, checkoutURL, plan, agentType, t
     const presentationHandoff = buildCheckoutHandoff({
         platform,
         url: plan.linkOnlyURL ?? checkoutURL,
+        mobileUrl: checkoutURL,
         amount,
         plan,
         ...(agentType ? { agentType } : {}),

package/dist/src/main.js

@@ -910,6 +910,9 @@ program
         await runCheckoutPresentation(backend, {
             checkoutID,
             displayToken,
+            ...(snap.lastCheckoutID === checkoutID && snap.lastCheckoutURL
+                ? { savedCheckoutURL: snap.lastCheckoutURL }
+                : {}),
             host,
             ...(options.target ? { target: options.target } : {}),
             ...(config.agentType ? { agentType: config.agentType } : {}),

package/dist/src/state/config.js

@@ -15,7 +15,7 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.9";
+export const CLI_VERSION = "2.1.10";
 export const API_CONTRACT_REVISION = "sha256:66a95bbc5ec9d7b35747cf87206c63dd45983f26de21afab582d8dd63bf198f7";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";

package/docs/agent/buyer/render-hosts.json

@@ -33,17 +33,17 @@
     {
       "agent_type": "workbuddy",
       "default_host": "plain-chat",
-      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files; show the amount and stop"
+      "responsibility": "execute handoff.agent_action exactly once to open the fully rendered handoff.url with present_files, then send handoff.mobile_url as a clickable link that jumps straight into Alipay or WeChat Pay on a phone; show the amount and stop"
     },
     {
       "agent_type": "zcode",
       "default_host": "plain-chat",
-      "responsibility": "open handoff.url immediately in the ZCode built-in browser and stop; only show the same clickable URL when the built-in browser is unavailable"
+      "responsibility": "open handoff.url immediately in the ZCode built-in browser, also send handoff.mobile_url as the phone-friendly entry, then stop; when the built-in browser is unavailable show both clickable links"
     },
     {
       "agent_type": "doubao-work",
       "default_host": "plain-chat",
-      "responsibility": "show handoff.url as the preferred same-phone checkout or authorization link and handoff.qr_image_url as the labeled save-or-scan fallback; state the amount for Checkout and stop"
+      "responsibility": "show handoff.mobile_url as the preferred same-phone checkout or authorization link and handoff.qr_image_url as the labeled save-or-scan fallback; state the amount for Checkout and stop"
     },
     {
       "agent_type": "kimi-code",
@@ -73,10 +73,11 @@
   "agent_rules": [
     "Agent Type is stable identity; Host is presentation and may be explicitly overridden.",
     "A local QR path is not visible until a desktop Agent attaches or renders that file on the human-facing surface; WorkBuddy never receives a local QR path.",
-    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser.",
-    "For zcode with plain-chat, open handoff.url in the built-in browser. Do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; use the same clickable URL only as fallback.",
-    "For doubao-work with plain-chat, show two labeled official links: handoff.url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
-    "If the WorkBuddy action fails, send the original handoff.url, report that it did not auto-open, and stop without creating another payment resource.",
+    "For workbuddy with plain-chat, execute handoff.agent_action exactly once; it calls present_files with handoff.url as the only files element and opens the rendered Card Link in the right-side browser, then send handoff.mobile_url so phone users can tap straight into Alipay or WeChat Pay.",
+    "For zcode with plain-chat, open handoff.url in the built-in browser and also send handoff.mobile_url as the phone entry; do not only paste text, download or rebuild a QR, or invent a private browser-tool payload; when the built-in browser is unavailable show both clickable links.",
+    "For doubao-work with plain-chat, show two labeled official links: handoff.mobile_url for direct same-phone opening and handoff.qr_image_url for saving or scanning on another device; do not parse credentials, download or rebuild the QR, or create an alternative resource.",
+    "If the WorkBuddy action fails, send the original handoff.url and handoff.mobile_url, report that it did not auto-open, and stop without creating another payment resource.",
+    "handoff.mobile_url is the phone-friendly Checkout URL; when the current client cannot open links in place (for example a mobile mini program), send it and tell the human to copy it into the phone browser where it can jump into Alipay or WeChat Pay. It is only returned when the handoff carries the complete token pair; when absent, handoff.url remains the entry.",
     "Do not claim the handoff was shown until both a usable payment image or QR and the Checkout URL are visible.",
     "IM Hosts that require a target must receive --target before Checkout creation. OpenClaw has no default Host; Kimi Code uses terminal.",
     "OpenClaw Telegram uses flat url/value buttons for deployed-version compatibility. A grant_confirmed callback carries only the Checkout ID, never a display token, and never proves payment or an active grant."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.1.9",
+  "version": "2.1.10",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {

package/skills/itpay/SKILL.md

@@ -76,6 +76,13 @@ platform whenever possible. Only show the same clickable URL when no browser
 or native action is available; never ask the human to run a command or rebuild
 a QR code.
 
+Checkout handoffs also carry `handoff.mobile_url`: send it alongside the main
+link and tell the human that on a phone it opens the cashier and can jump
+straight into Alipay or WeChat Pay. When the current client cannot open links
+itself (for example a mobile mini program without a side panel), send
+`mobile_url` and tell the human to copy it into the phone's browser if it does
+not open in place.
+
 ## Serve The Human
 
 - Ask the human only to choose, authorize, pay, provide required contact