@itpay/cli 2.1.33 → 2.1.40

package/dist/src/commands/skill.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CODEX_WAIT_GUIDANCE } from "./install.js";
 import { declaredAgentType } from "../state/agent_type.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
 const commandDir = dirname(fileURLToPath(import.meta.url));
@@ -19,6 +20,8 @@ export function runSkillShow(name, options = {}) {
     }
     validateSkill(content);
     const agentType = options.agentType ?? declaredAgentType();
+    if (agentType?.startsWith("codex-"))
+        content += `\n## Codex command continuation\n\n${CODEX_WAIT_GUIDANCE}\n`;
     const envelope = {
         status: "shown",
         result: { skill: ITPAY_SKILL, content },

package/dist/src/main.js

@@ -1,3 +1,4 @@
+import { runAftercareList, runAftercareCreate, runAftercareGet, runAftercareRespond } from "./commands/aftercare.js";
 import { agentAuth } from "./state/account_auth.js";
 import { registerSell } from "./sell/commands.js";
 import { readFileSync as readWorkflowInputFile, statSync as statWorkflowInputFile } from "node:fs";
@@ -6,7 +7,7 @@ import { runServicesRun } from "./commands/services.js";
 // services/backend/internal/httpapi/handlers/*.go. Commands only
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
-import { BackendOverrideError, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
+import { BackendOverrideError, API_CONTRACT_REVISION, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
 import { DeviceAuthority, DeviceAuthorizationError, DeviceLockBusyError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
@@ -128,9 +129,6 @@ function reportCLIError(error, contract) {
         error.code === "client_compatibility_headers_required" ||
         error.code === "platform_release_unavailable" ||
         (error.status === 404 && error.code === "unknown_error"));
-    const requiredCLIVersion = incompatible && error instanceof HttpError && /^\d+\.\d+\.\d+$/.test(error.payload?.minimum_cli_version ?? "")
-        ? error.payload.minimum_cli_version
-        : undefined;
     const backendInternal = error instanceof HttpError && error.status === 500 && error.code === "internal_error";
     const providerConnectionUnavailable = error instanceof HttpError && error.code === "provider_connection_unavailable";
     const providerTemporary = error instanceof HttpError && error.code === "provider_temporarily_unavailable";
@@ -155,7 +153,7 @@ function reportCLIError(error, contract) {
             reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
         }] : [];
     const authorizationInstruction = stateError
-        ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
+        ? `当前运行环境无法写入 owner-only Device 状态；受阻路径 ${stateError.blockedPath ?? "~/.itpay-v3"}，操作 ${stateError.operation}（${stateError.causeCode}）。保持同一 Node、CLI 和 Agent Type，修复该路径持久写权限后重试原命令；不要手工创建 lock、删除 identity、随意更换 HOME 或换运行时。`
         : lockError
             ? "另一个进程仍在更新本地身份。执行 recovery 检查；若持有者仍活跃，等待后继续原任务，不要删除锁或重建身份。"
             : error instanceof HttpError && error.code === "agent_device_session_required"
@@ -176,10 +174,13 @@ function reportCLIError(error, contract) {
                 code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
-            ...(commandError?.result ? { result: commandError.result } : requiredCLIVersion ? {
+            ...(commandError?.result ? { result: commandError.result } : incompatible && error instanceof HttpError ? {
                 result: {
                     current_cli_version: CLI_VERSION,
-                    required_cli_version: requiredCLIVersion,
+                    current_api_contract_revision: API_CONTRACT_REVISION,
+                    platform_api_contract_revision: error.payload?.api_contract_revision ?? null,
+                    minimum_cli_version: error.payload?.minimum_cli_version ?? null,
+                    maximum_cli_major: error.payload?.maximum_cli_major ?? null,
                 },
             } : transportError ? {
                 result: {
@@ -199,9 +200,7 @@ function reportCLIError(error, contract) {
                 },
             } : {}),
             instruction: incompatible
-                ? requiredCLIVersion
-                    ? distributionUpgradeInstruction()
-                    : "告诉用户 ItPay 当前版本信息无法验证，因此本次服务不能安全继续。停止所有 ItPay 和 npm 操作；不要转述技术错误、猜版本、切换 Agent Type 或删除 Device 身份。"
+                ? "当前 CLI 与 Backend 合约不兼容或无法核验。minimum_cli_version 仅是协议门槛，不是已验证的推荐安装包。停止本轮，请维护方提供与当前 Backend 配套的制品；不要猜版本、降级、切换 Agent Type 或删除 Device 身份。"
                 : backendInternal
                     ? "告诉用户 ItPay 当前暂时无法完成这项服务并停止。不要转述内部错误、重试、修改身份、创建替代服务或进入任何付费路径。"
                     : providerConnectionUnavailable
@@ -217,18 +216,18 @@ function reportCLIError(error, contract) {
                                         : capabilityInputInvalid
                                             ? "Agent按当前合同模板修正字段和JSON层级，保留用户原始需求，继续同一次服务。不要让用户修技术输入，只有真实业务歧义才询问。"
                                             : transportError
-                                                ? transportError.attempts > 1
-                                                    ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
-                                                    : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
+                                                ? contract?.initialization
+                                                    ? "本轮初始化检查未完成；CLI 已结束有限的网络尝试，尚未确认后端或设备就绪。结束本轮，网络恢复后可重新检查；不要继续登录或业务操作。"
+                                                    : transportError.attempts > 1
+                                                        ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
+                                                        : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
                                                 : backendOverrideError
                                                     ? "移除 ITPAY_BACKEND_URL 使用正式环境，或按当前测试目标准确设置为 https://sandbox.itpay.ai 或 https://dev.itpay.ai。不要通过切换环境规避当前错误。"
                                                     : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
             ...(commandError?.interaction ? { interaction: commandError.interaction } : {}),
-            recovery: incompatible
-                ? requiredCLIVersion
-                    ? [distributionUpgradeAction(requiredCLIVersion)]
-                    : []
+            recovery: incompatible || (transportError && contract?.initialization)
+                ? []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
                     : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
@@ -275,15 +274,9 @@ function distributionUpgradeAction(version) {
                 reason: `更新包含 ItPay CLI ${version} 的 Kimi plugin`,
             };
         default:
-            return { command: `npm install -g @itpay/cli@${version}`, reason: "安装 Backend 指定的兼容 CLI 版本" };
+            return { command: `npm install -g @itpay/cli@${version}`, reason: "恢复当前 CLI 版本的完整安装包" };
     }
 }
-function distributionUpgradeInstruction() {
-    if (cliDistribution() === "npm") {
-        return "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。";
-    }
-    return "当前平台 bundle 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，更新平台 Skill/plugin 后启动新会话，确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要运行 npm、猜测版本、切换 Agent Type 或删除 Device 身份。";
-}
 program
     .command("readyz")
     .description("Probe the V3 backend readiness endpoint")
@@ -301,10 +294,9 @@ program
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
             code: "backend_unavailable",
+            initialization: true,
             instruction: `当前官方 Backend ${config.baseURL} 不可用；恢复前不要继续下单，也不要切换环境。`,
-            recovery: [
-                { command: "itpay readyz", reason: "重试当前官方 Backend 的可用性检查" },
-            ],
+            recovery: [],
         });
     }
 });
@@ -328,7 +320,7 @@ for (const action of ["login", "status"]) {
             writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.json) });
         }
         catch (error) {
-            reportCLIError(error, { jsonOutput: Boolean(options.json), code: "account_login_failed", instruction: "完成官方网页登录后重试 itpay auth status；不要清除设备登记。" });
+            reportCLIError(error, { jsonOutput: Boolean(options.json), code: "account_login_failed", initialization: true, instruction: "本轮授权检查未完成；保留设备及已有授权状态，按明确错误原因恢复。不要自动发起新的登录。" });
         }
     });
 }
@@ -1141,6 +1133,49 @@ feedback
         });
     }
 });
+const aftercare = program.command("aftercare").description("Railway manual refund/change requests; never automatic supplier operations");
+aftercare.command("list").requiredOption("--order <order_id>").option("--json").action(async (options) => {
+    try {
+        const config = loadConfig();
+        writeCommandEnvelope(await runAftercareList(newBackendClient(config), options.order), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_read_failed", instruction: "核对原订单与当前身份；铁路人工售后不改变平台内容授权，不换身份绕过。", recovery: [{ command: "itpay services list --json", reason: "找回当前身份原订单" }] });
+    }
+});
+aftercare.command("create").requiredOption("--order <order_id>").requiredOption("--input-json <file>").option("--json").action(async (options) => {
+    const recovery = [{ command: `itpay aftercare list --order ${options.order} --json`, reason: "读取原订单当前行程与完整申请模板" }];
+    try {
+        const config = loadConfig();
+        const input = readInputJsonObject(options.inputJson, "rail_aftercare_input_invalid", recovery);
+        writeCommandEnvelope(await runAftercareCreate(newBackendClient(config), config, options.order, input), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_create_failed", instruction: "保留原申请与用户范围，按实际错误读取当前模板或办理状态；不猜金额/身份，不重复未知操作。", recovery });
+    }
+});
+aftercare.command("get").argument("<case_id>").option("--json").action(async (id, options) => {
+    try {
+        const config = loadConfig();
+        writeCommandEnvelope(await runAftercareGet(newBackendClient(config), id), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_read_failed", instruction: "核对当前身份的原申请，不换身份或探测其他申请。", recovery: [] });
+    }
+});
+for (const action of ["respond", "cancel"]) {
+    aftercare.command(action).argument("<case_id>").requiredOption("--input-json <file>").option("--json").action(async (id, options) => {
+        const recovery = [{ command: `itpay aftercare get ${id} --json`, reason: "读取原申请当前版本与明确下一步" }];
+        try {
+            const config = loadConfig();
+            const input = readInputJsonObject(options.inputJson, "rail_aftercare_input_invalid", recovery);
+            writeCommandEnvelope(await runAftercareRespond(newBackendClient(config), id, input, action === "cancel"), { jsonOutput: Boolean(options.json) });
+        }
+        catch (error) {
+            reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_response_failed", instruction: "按原申请当前版本处理；取消不撤回供应商操作，未知资金不重试。", recovery });
+        }
+    });
+}
 const refund = program
     .command("refund")
     .enablePositionalOptions()
@@ -1211,7 +1246,7 @@ refund.command("get").argument("<refund_request_id>").option("--json", "output J
         });
     }
 });
-refund.command("watch").argument("<refund_request_id>").option("--interval <seconds>", "poll interval", Number, 2).option("--timeout <seconds>", "timeout", Number, 120).option("--json", "output JSON instead of terminal text").action(async (id, options) => {
+refund.command("watch").argument("<refund_request_id>").option("--interval <seconds>", "poll interval", Number, 2).option("--timeout <seconds>", "bounded wait; returns on change/manual attention", Number, 20).option("--json", "output JSON instead of terminal text").action(async (id, options) => {
     const config = loadConfig();
     try {
         await runWatchRefund(newBackendClient(config), id, {
@@ -1371,7 +1406,8 @@ function readInputJsonObject(file, code, recovery) {
 const services = program.command("services").description("Generic V3 Service Execution commands");
 services
     .command("run")
-    .description("Run a published service and present Checkout when payment is required")
+    .description("Run a declared service operation; preparation approval is required before Checkout")
+    .option("--operation <operation_id>", "operation declared by the public service definition")
     .argument("<service_id>")
     .option("--input-json <file>", "JSON object containing the service input")
     .option("--execution <execution_id>", "resume the same execution")
@@ -1382,16 +1418,31 @@ services
     .action(async (serviceID, options) => {
     const config = loadConfig();
     try {
-        const input = options.inputJson
+        let input = options.inputJson
             ? readInputJsonObject(options.inputJson, "workflow_input_invalid", [
                 { command: `itpay services run ${serviceID} --json`, reason: "重新读取服务输入声明" },
             ])
             : undefined;
+        let continuation;
+        if (options.operation && input !== undefined) {
+            const parameters = input.input;
+            if (typeof parameters !== "object" || parameters === null || Array.isArray(parameters))
+                throw new CommandContractError("operation_input_invalid", "operation JSON must include an input object", "使用公开操作返回的完整JSON模板，顶层input是业务输入；保留服务端continuation。", []);
+            const reference = input.continuation;
+            if (reference !== undefined) {
+                if (typeof reference !== "object" || reference === null || Array.isArray(reference) || !("service_execution_id" in reference) || !("snapshot_id" in reference) || typeof reference.service_execution_id !== "string" || typeof reference.snapshot_id !== "string")
+                    throw new CommandContractError("operation_input_invalid", "invalid continuation reference", "保留结果详情返回的continuation，不猜执行或snapshot。", []);
+                continuation = { service_execution_id: reference.service_execution_id, snapshot_id: reference.snapshot_id };
+            }
+            input = Object.fromEntries(Object.entries(parameters));
+        }
         if (!Number.isFinite(options.timeout) || options.timeout < 0 || options.timeout > 600) {
             throw new Error("timeout must be between 0 and 600 seconds");
         }
         await runServicesRun(newBackendClient(config), config, serviceID, input, {
             ...(options.execution ? { executionID: options.execution } : {}),
+            ...(options.operation ? { operationID: options.operation } : {}),
+            ...(continuation ? { continuation } : {}),
             jsonOutput: Boolean(options.json),
             host: withHost(options.host, config.agentType, options.target),
             ...(options.target ? { target: options.target } : {}),

package/dist/src/render/checkout_handoff.js

@@ -0,0 +1,101 @@
+import { buildOpenClawTelegramAction } from "./telegram.js";
+export function shouldPrepareLocalCheckoutImage(platform) {
+    return platform === "markdown";
+}
+export function isWorkBuddyPlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
+}
+export function isZCodePlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "zcode" && platform === "plain_chat";
+}
+export function isLinkOnlyBrowserAgent(agentType, platform) {
+    return isWorkBuddyPlainChat(agentType, platform) || isZCodePlainChat(agentType, platform);
+}
+export function buildWorkBuddyPresentFilesAction(url) {
+    return {
+        tool: "present_files",
+        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 url = input.plan?.localSimulation && input.mobileUrl && hasCompleteCheckoutTokens(input.mobileUrl) ? input.mobileUrl : input.url;
+    const handoff = { url, ...(input.plan?.localSimulation ? { environment: "local_simulation", query: "live", transactions: "simulated" } : {}) };
+    // 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 = !input.plan?.localSimulation && 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(url);
+    }
+    if (input.platform === "markdown") {
+        if (input.localPath)
+            handoff.qr_local_path = input.localPath;
+        if (input.markdown)
+            handoff.markdown = input.markdown;
+    }
+    else if (input.platform === "plain_chat" && input.qrImageURL && !isLinkOnlyBrowserAgent(input.agentType, input.platform)) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    else if (input.platform === "telegram" && input.qrImageURL) {
+        handoff.qr_image_url = input.qrImageURL;
+    }
+    if (input.agentType?.trim().toLowerCase() === "openclaw" && input.platform === "telegram" && input.plan && input.target) {
+        handoff.agent_action = buildOpenClawTelegramAction(input.plan, input.target);
+    }
+    return {
+        handoff,
+        instruction: input.plan?.localSimulation
+            ? `本地实验：铁路与地图查询真实，授权、通知和交易模拟，不会扣款。在本机打开 handoff.url 模拟付款入口，金额 ${input.amount}；仅本机桌面可达。${workBuddyAction ? "按 handoff.agent_action 原样打开一次。" : "展示原入口。"}等待用户操作后读取同一 Checkout；不创建替代订单，用户声明不证明模拟付款已确认。`
+            : `先展示官方入口，再做非必要记忆或日志；保留必需安全检查和宿主权限。${checkoutHandoffInstruction(input.agentType, input.platform, input.amount, Boolean(mobileUrl))}`,
+    };
+}
+function checkoutHandoffInstruction(agentType, platform, amount, hasMobileLink) {
+    if (isWorkBuddyPlainChat(agentType, platform)) {
+        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)) {
+        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") {
+        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") {
+        const mobileSentence = hasMobileLink ? "，并附 handoff.mobile_url 供手机端点击直达支付" : "";
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见${mobileSentence}，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
+    if (platform === "terminal") {
+        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") {
+        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。`;
+    }
+    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/render/checkout_plan.js

@@ -0,0 +1,47 @@
+import { platformKeyForHost } from "./plan.js";
+import { isLinkOnlyBrowserAgent } from "./checkout_handoff.js";
+import { qualifyItPayCommand } from "../state/agent_type.js";
+// --- checkout QR plan ---
+export function buildCheckoutQRPlan(input) {
+    const summary = input.localSimulation ? "在本机打开模拟付款入口；铁路与地图查询真实，授权、通知和交易模拟，不会扣款。" : `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
+    const isPayment = input.paymentIntentID != null;
+    const afterCommand = qualifyItPayCommand(`itpay checkout --id ${input.checkoutID} --token ${input.displayToken}${input.locale === "en" ? " --locale en" : ""} --json`, input.agentType);
+    const platform = {
+        text: summary,
+        links: [
+            { label: "打开付款页面", url: input.checkoutURL },
+        ],
+        buttons: [
+            { label: "打开收银台", kind: "url", url: input.checkoutURL },
+            ...(input.checkoutID
+                ? [{ label: "查询 Checkout 状态", kind: "callback", intent: "check_checkout_status", ref: input.checkoutID }]
+                : []),
+        ],
+        blocks: [],
+        ...(input.qrPNGURL ? { media: [{ url: input.qrPNGURL, label: "Branded QR", mimeType: "image/png" }] } : {}),
+    };
+    const plan = {
+        kind: isPayment ? "payment_qr" : "checkout_qr",
+        ...(input.localSimulation ? { localSimulation: true } : {}),
+        host: input.host,
+        summary,
+        url: input.qrPayload,
+        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
+        preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
+        checkoutID: input.checkoutID,
+        platform,
+        afterActionCommand: afterCommand,
+        afterActionLabel: "扫码或点击链接完成支付后，执行以下命令查询状态：",
+    };
+    if (input.orderItems)
+        plan.orderItems = input.orderItems;
+    if (input.orderCurrency)
+        plan.orderCurrency = input.orderCurrency;
+    if (input.paymentMethod)
+        plan.paymentMethod = input.paymentMethod;
+    if (input.paymentStatus)
+        plan.paymentStatus = input.paymentStatus;
+    if (input.paymentIntentID)
+        plan.paymentIntentID = input.paymentIntentID;
+    return plan;
+}

package/dist/src/services/adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/presentation.js

@@ -0,0 +1,198 @@
+import { serviceAdapter } from "./registry.js";
+import { refundStateEnvelope } from "./shared/refund.js";
+import { appendFeedbackPostmortemInstruction, isTerminalServiceExecutionStatus } from "./shared/envelope.js";
+import { terminalExecutionEnvelope, serviceDeliveryMode, normalizeGrantStatus, paidContinuation, purchaseConfirmationInstruction, serviceAllowedActionCommand } from "./shared/platform.js";
+export function servicesNextEnvelope(model) {
+    const execution = model.execution;
+    const adapter = serviceAdapter(execution);
+    const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    const lockedRefund = model.refunds.find((refund) => refund.access_locked);
+    if (lockedRefund) {
+        const refundState = refundStateEnvelope(lockedRefund, "delivery_locked");
+        return { ...refundState, result: { ...refundState.result, service_execution_id: execution.service_execution_id, refund: { refund_request_id: lockedRefund.refund_request_id, status: lockedRefund.status, ...(lockedRefund.failure_class ? { failure_class: lockedRefund.failure_class } : {}) } },
+            next: refundState.next ? { command: `itpay refund get ${lockedRefund.refund_request_id} --json`, reason: "读取同一退款权威状态" } : null };
+    }
+    const unsettledPayment = model.payment_bindings.some(binding => typeof binding.status === "string" && ["pending", "outcome_unknown", "unknown", "processing"].includes(binding.status));
+    if (unsettledPayment)
+        return { status: "payment_outcome_pending", result: { service_execution_id: execution.service_execution_id, payment_state: "unsettled", checkout_ids: model.checkout_bindings.map(binding => binding.checkout_id) }, instruction: "原付款结果尚未确认。保留同一执行、Checkout和订单，只核对权威事实；不创建新报价、购物车、付款入口或购买，也不宣称已付款或服务已完成。", next: null, recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅用户要求或平台恢复后核对同一付款事实" }] };
+    // Terminal facts take priority unless the locked adapter supports same-execution recovery.
+    if (!(adapter.preservesTerminalRecovery(model)) && isTerminalServiceExecutionStatus(execution.status) && !["completed", "delivery_completed"].includes(execution.status)) {
+        // Preserve the registered adapter's safe failure facts even at execution terminal.
+        const failedWorkflow = execution.status === "failed" && model.workflow?.status === "failed" ? adapter.workflow(model) : undefined;
+        if (failedWorkflow)
+            return { ...failedWorkflow, next: null };
+        const terminal = terminalExecutionEnvelope(model);
+        if (terminal)
+            return terminal;
+    }
+    const latestRun = model.execution_requests?.filter((request) => request.execution_kind === "service.execution.run").at(-1);
+    if (latestRun && ["pending", "started"].includes(latestRun.status) && model.workflow?.status !== "failed") {
+        return {
+            status: "running",
+            result: { service_execution_id: execution.service_execution_id, execution_request_id: latestRun.execution_request_id },
+            instruction: "任务仍在排队或执行中，稍后读取同一任务。不要重新查询、重复提交输入或把等待状态当作零结果。",
+            next: { command: `itpay services next ${execution.service_execution_id} --json`, reason: "稍后读取同一任务状态" },
+            recovery: [],
+        };
+    }
+    const businessState = adapter.projectState(model);
+    if (businessState)
+        return businessState;
+    if (latestRun && ["failed", "cancelled"].includes(latestRun.status) && !model.workflow_entry) {
+        return {
+            status: latestRun.status,
+            result: { service_execution_id: execution.service_execution_id },
+            instruction: "本次任务未完成，需要检查同一任务的处理记录；这不表示没有结果。不要自动重新发起。",
+            next: null,
+            recovery: [{ command: `itpay services events ${execution.service_execution_id} --json`, reason: "读取同一任务的处理记录" }],
+        };
+    }
+    if (!adapter.supported)
+        return { status: "presentation_contract_unavailable", result: { service_execution_id: execution.service_execution_id, service_id: execution.service_id, service_contract_version_id: execution.service_contract_version_id, public_binding: execution.public_binding }, instruction: "当前锁定呈现合同不受本候选支持；保留执行与已有结果并停止，取得兼容CLI后读取同一执行，不猜模式或启动新购买。", next: null, recovery: [] };
+    const workflowEnvelope = adapter.workflow(model);
+    if (workflowEnvelope)
+        return workflowEnvelope;
+    const terminalEnvelope = terminalExecutionEnvelope(model);
+    if (terminalEnvelope)
+        return terminalEnvelope;
+    const currentItems = model.current_result_items ?? [];
+    const savedRailResult = adapter.savedResult(model);
+    if (savedRailResult)
+        return savedRailResult;
+    const delivery = currentDelivery;
+    const deliveryMode = serviceDeliveryMode(model);
+    const candidateSelection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+    if (candidateSelection && currentItems.length > 0) {
+        const paidCapability = delivery?.capability_id
+            ? model.capabilities.find((capability) => capability.capability_id === delivery.capability_id && capability.requires_payment)
+            : undefined;
+        return {
+            status: "candidate_selection_available",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(deliveryMode ? { delivery_mode: deliveryMode } : {}),
+                items: currentItems.map((item) => ({
+                    rank: item.rank,
+                    title: item.display_title,
+                    safe_payload: item.safe_payload,
+                })),
+            },
+            instruction: paidCapability
+                ? "付费搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload 或自动购买后续服务。"
+                : "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时才提交对应编号；不要提及 safe_payload、Execution 或内部 ID。",
+            next: null,
+            interaction: candidateInteraction(execution.service_execution_id),
+            recovery: [],
+        };
+    }
+    if (deliveryMode === "agent_visible_result") {
+        const items = currentItems.map((item) => ({
+            rank: item.rank,
+            title: item.display_title,
+            safe_payload: item.safe_payload,
+        }));
+        const selection = model.allowed_actions?.find((action) => action.type === "select_candidate");
+        const deliveryGuidance = adapter.deliveryGuidance(model);
+        const instruction = (delivery?.order_id
+            ? appendFeedbackPostmortemInstruction(items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。", "delivered")
+            : items.length > 0
+                ? selection
+                    ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才提交 interaction 中的对应编号；不要提及 safe_payload。"
+                    : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Arazzo、safe_payload 或内部 ID。"
+                : "告诉用户本次查询得到 0 个结果并停止。Agent 不读取其他交付、不重放当前查询、修改输入或创建新查询。")
+            + (deliveryGuidance?.instruction && items.length > 0 ? ` ${deliveryGuidance.instruction}` : "");
+        return {
+            status: items.length > 0 ? "result_ready" : "no_result",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                ...(delivery?.order_id ? { order_id: delivery.order_id, aftercare: { optional: true, command: `itpay feedback submit --order ${delivery.order_id} --json`, reason: "结果答复后按需复盘；不猜评分" } } : {}),
+                delivery_mode: deliveryMode,
+                items,
+            },
+            instruction,
+            next: null,
+            ...(selection ? { interaction: candidateInteraction(execution.service_execution_id) } : {}),
+            recovery: deliveryGuidance?.recovery ?? [],
+        };
+    }
+    if (deliveryMode === "vault_artifact") {
+        const grantStatus = normalizeGrantStatus(delivery?.grant_status);
+        const grantActive = grantStatus === "active";
+        const grantPending = grantStatus === "pending";
+        return {
+            status: grantActive ? "grant_active" : grantPending ? "result_preparing" : "human_authorization_required",
+            result: {
+                service_execution_id: execution.service_execution_id,
+                ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
+                delivery_mode: deliveryMode,
+                grant_status: grantStatus,
+                ...(delivery?.preparation ? { preparation: delivery.preparation } : {}),
+                ...(grantActive && delivery?.grant_expires_at ? { grant_expires_at: delivery.grant_expires_at } : {}),
+            },
+            instruction: grantActive
+                ? "先告诉用户付费内容已经准备好且当前读取授权有效；立即读取并只解释授权字段，遵守范围与到期时间。"
+                : grantPending
+                    ? "告诉用户：授权已经完成，付费结果仍在同一订单下准备，不需要再次付款或授权。然后只执行 next.command 查询同一笔服务；Agent 不创建新服务、付款页面或数据请求，也不提前读取。"
+                    : "先告诉用户付费内容已经归入当前订单，但需要本人确认一次读取授权；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+            next: grantPending ? {
+                command: `itpay services next ${execution.service_execution_id} --json`,
+                reason: "等待同一 Execution 的交付准备完成",
+            } : {
+                command: `itpay services read-result ${execution.service_execution_id} --json`,
+                reason: grantActive ? "读取当前有效 grant 的结果" : "仅在用户确认授权后执行",
+            },
+            recovery: [],
+        };
+    }
+    const allowedActions = model.allowed_actions ?? [];
+    const preferred = allowedActions[0];
+    if (preferred?.type === "prepare_quote") {
+        const continuation = paidContinuation(model, preferred, {});
+        if (continuation) {
+            return {
+                status: execution.status,
+                result: {
+                    service_execution_id: execution.service_execution_id,
+                    service_id: execution.service_id,
+                    phase: execution.phase,
+                    checkout: continuation.checkout,
+                },
+                instruction: purchaseConfirmationInstruction(execution.status === "quota_exhausted" ? "quota_exhausted" : "candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose),
+                next: continuation.next,
+                recovery: [],
+            };
+        }
+    }
+    const next = preferred ? serviceAllowedActionCommand(model, preferred) : null;
+    return {
+        status: execution.status,
+        result: {
+            service_execution_id: execution.service_execution_id,
+            service_id: execution.service_id,
+            phase: execution.phase,
+            allowed_actions: allowedActions.map((action) => ({
+                type: action.type,
+                ...(action.capability_id ? { capability_id: action.capability_id } : {}),
+                requires_human: action.requires_human,
+            })),
+        },
+        instruction: preferred?.type === "resume_checkout"
+            ? "这笔服务已经有付款页面。只执行 next.command 恢复并展示同一个入口；Agent 不创建新的报价、购物车、付款页面或服务。"
+            : preferred?.type === "wait"
+                ? "告诉用户付款和订单已经确认，结果仍在同一笔服务中处理，不需要再次付款；如果最终无法交付，将从原订单检查退款路径。稍后只执行 next.command；Agent 不创建新服务、付款页面或数据请求，也不承诺退款结果。"
+                : preferred?.requires_human
+                    ? "当前下一步需要用户明确选择；先展示必要信息并等待确认。"
+                    : preferred ? "执行服务端返回的唯一首选动作；不要猜测其他 capability。" + adapter.locationInstruction(model.capabilities.find((item) => item.capability_id === preferred.capability_id)?.input_schema) : "当前没有后续动作。",
+        next,
+        recovery: [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "仅在当前动作异常时检查时间线" }],
+    };
+}
+function candidateInteraction(id) {
+    return { schema_version: "itpay.interaction.v1", stage: "candidate_selection_required", input_template: { command: `itpay services action ${id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`, required_input: ["rank"], executable: false } };
+}