@itpay/cli 2.1.41 → 2.1.44

package/dist/src/commands/presentation.js

@@ -0,0 +1,153 @@
+// Deterministic PresentationResolver (spec 03 §5): business state first, then
+// declared viewer/executor capabilities, then the user's explicit choice and
+// failure history. Output is one recommended route plus at most two feasible
+// alternatives — never a parallel burst of open + send.
+//
+// Routes are abstract kinds; the caller maps them to concrete handoff fields
+// (url, card image, qr). "unknown" capability answers are never treated as
+// "yes", and a route that already failed is not retried without a new reason.
+const yes = (value) => value === "yes";
+export function resolvePresentation(input) {
+    const blocker = businessBlocker(input.business);
+    if (blocker) {
+        return {
+            blocker,
+            recommended: "none",
+            alternatives: [],
+            routes: [],
+            communication: communicationForBlocker(blocker),
+        };
+    }
+    const caps = input.capabilities;
+    const local = input.executor_locality === "same_device";
+    const routes = [];
+    if (input.viewer === "desktop") {
+        if (yes(caps.user_visible_browser))
+            routes.push("open_embedded_browser");
+        if (local && yes(caps.system_browser))
+            routes.push("open_system_browser");
+        if (yes(caps.clickable_https))
+            routes.push("show_link");
+        if (yes(caps.image_visible))
+            routes.push("show_official_image");
+        if (yes(caps.user_visible_terminal) && yes(caps.other_device_scan))
+            routes.push("show_terminal_qr");
+    }
+    else if (input.viewer === "mobile") {
+        if (yes(caps.native_url_button))
+            routes.push("show_mobile_button");
+        if (yes(caps.clickable_https))
+            routes.push("show_mobile_link");
+        if (yes(caps.user_visible_browser))
+            routes.push("open_user_browser");
+        if (local && yes(caps.system_browser))
+            routes.push("open_system_browser");
+        // QR never targets the same phone the human is holding.
+    }
+    else {
+        if (yes(caps.clickable_https))
+            routes.push("show_link");
+        if (routes.length === 0 && yes(caps.image_visible))
+            routes.push("ask_viewer_device");
+    }
+    // Relay is a consented fallback, not a presentation route — it only appears
+    // when an issued, verified contact option exists.
+    if (input.verified_phone_option === true)
+        routes.push("request_sms_consent");
+    if (input.verified_email_option === true)
+        routes.push("request_email_consent");
+    routes.push("show_copyable_entry");
+    const failed = new Set(input.failed_routes ?? []);
+    const feasible = routes.filter((route) => !failed.has(route));
+    const chosen = input.explicit_choice;
+    if (chosen && feasible.includes(chosen)) {
+        feasible.splice(feasible.indexOf(chosen), 1);
+        feasible.unshift(chosen);
+    }
+    const ranked = feasible.length > 0 ? feasible : ["show_copyable_entry"];
+    const [recommended, ...alternatives] = ranked;
+    return {
+        recommended: recommended,
+        alternatives: alternatives.slice(0, 2),
+        routes: ranked.slice(0, 3),
+        communication: {
+            tell: tellForRoute(recommended),
+            wait_for: "人完成官方页面上的确认/付款；dispatch 成功不等于已付款",
+            must_convey: [
+                "真实金额与订单归属以 owner 返回为准",
+                "已发起打开不代表已显示或已付款",
+                ...(input.business.amount_minor === undefined ? ["金额尚未确认，不称锁价或最终价"] : []),
+            ],
+        },
+    };
+}
+function businessBlocker(business) {
+    if (business.commerce_policy === "blocked")
+        return "policy_blocked";
+    if (business.commerce_policy === "review")
+        return "policy_review_required";
+    if (business.payment_state !== "unpaid")
+        return "read_same_order";
+    if (business.quote_valid !== true)
+        return "recover_expired_quote";
+    if (typeof business.amount_minor !== "number" || business.amount_minor <= 0)
+        return "read_same_order";
+    return undefined;
+}
+function communicationForBlocker(blocker) {
+    switch (blocker) {
+        case "policy_blocked":
+            return { tell: "该服务在当前宿主/准入策略下不可用，不绕外链或消息逃避。", wait_for: "用户更换获准渠道", must_convey: ["技术与准入分开说明"] };
+        case "policy_review_required":
+            return { tell: "当前准入策略要求复核，不发起展示动作。", wait_for: "准入复核结果", must_convey: ["不是业务失败"] };
+        case "read_same_order":
+            return { tell: "该订单不处于待付款状态；先读取原订单，不展示付款入口、不新建支付动作。", wait_for: "原订单状态", must_convey: ["用户声称已付仍须核对原单"] };
+        case "recover_expired_quote":
+            return { tell: "报价已失效或过期；读取原执行由 owner 重新核价，不向人收取旧金额。", wait_for: "新的 owner 报价", must_convey: ["旧二维码/入口不再有效"] };
+    }
+}
+function tellForRoute(route) {
+    switch (route) {
+        case "open_embedded_browser":
+        case "open_system_browser":
+        case "open_user_browser":
+            return "已发起打开官方页面；若用户未看到，换一种方式，仍是同一订单。";
+        case "show_link":
+        case "show_mobile_link":
+            return "把官方链接作为可点击入口交给用户。";
+        case "show_mobile_button":
+            return "展示原生 URL 按钮直达官方页。";
+        case "show_official_image":
+            return "展示官方图片入口（另一台设备用）。";
+        case "show_terminal_qr":
+            return "展示二维码供另一台设备扫码。";
+        case "request_sms_consent":
+            return "建议把订单入口发到已验证的手机尾号；征得明确同意后发送一条。";
+        case "request_email_consent":
+            return "建议把订单入口发到已验证的邮箱；征得明确同意后发送一封。";
+        case "ask_viewer_device":
+            return "无法判断用户在看哪种设备；最多澄清一次设备类型。";
+        case "show_copyable_entry":
+            return "给出可复制的官方入口并说明如何打开。";
+        default:
+            return "当前无可行展示方式；只说明状态，等待用户给出可用渠道。";
+    }
+}
+export function resolveRelay(input) {
+    if (!input.backendCapability) {
+        return {
+            kind: "unavailable",
+            reason: "当前 Backend 未提供消息转发（relay）能力；改用官方链接或二维码呈现，不得伪造发送结果。",
+        };
+    }
+    if (!input.relayOption) {
+        return { kind: "invalid", reason: "--relay-option 必须是服务端已签发的脱敏联系人引用。" };
+    }
+    if (!input.requestKey || !input.requestKey.trim()) {
+        return { kind: "invalid", reason: "--request-key 是必填的稳定幂等键。" };
+    }
+    if (!input.confirmRelay) {
+        return { kind: "needs_consent" };
+    }
+    return { kind: "unavailable", reason: "relay 后端未启用。" };
+}

package/dist/src/commands/rail_catalog.js

@@ -0,0 +1 @@
+export * from "../services/rail/catalog.js";

package/dist/src/commands/readyz.js

@@ -8,7 +8,7 @@ export async function runReadyz(backend, options = {}) {
         status: response.status,
         result: { backend: "available", backend_url: backendURL, environment, ...(options.agentType ? { agent_type: options.agentType } : {}) },
         instruction: environment === "development"
-            ? "ItPay dev 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 dev Backend。"
+            ? `ItPay 开发环境 ${backendURL} 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 Backend。`
             : "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
         next: { command: "itpay skill show itpay --json", reason: "加载完整操作与安全规则" },
         recovery: [],

package/dist/src/commands/refund.js

@@ -1,3 +1,4 @@
+import { refundStateEnvelope } from "../services/shared/refund.js";
 import { operationID } from "../state/config.js";
 import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
@@ -12,46 +13,6 @@ export async function runRefund(backend, config, options) {
         plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
     });
 }
-function refundStateEnvelope(refund, status) {
-    const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
-    let instruction = refund.decision_mode === "manual"
-        ? "先告诉用户退款已进入人工审核，原交付保持冻结；人工审核不等于拒绝，等待服务器决定，不要重复申请或承诺结果。"
-        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不要重复申请、reveal、授权或读取结果。";
-    if (!refund.access_locked)
-        instruction = "先告诉用户退款当前没有锁定交付；按服务器事实解释当前状态，不要自行推断退款结果、到账时间或交付资格。";
-    if (refund.status === "succeeded")
-        instruction = "先告诉用户退款已由 ItPay 确认成功，原交付永久关闭；不需要继续跟踪或重复申请。";
-    if (refund.status === "cancelled" || refund.status === "rejected")
-        instruction = "先告诉用户退款没有执行，交付资格可以恢复；旧读取授权不会复活，需要用户重新授权。不要把取消或拒绝说成退款成功。";
-    if (refund.status === "failed") {
-        if (refund.failure_class === "known_no_effect")
-            instruction = "先告诉用户本次退款请求确认未发送，不能说退款已成功；Agent 不自行重试，请用户等待平台管理员决定是否重新执行。";
-        else if (refund.failure_class === "retryable")
-            instruction = "先告诉用户渠道明确返回可重试失败，但 Agent 不会自行重试或重复申请；请用户等待平台管理员处理。";
-        else if (refund.failure_class === "outcome_unknown")
-            instruction = "先告诉用户退款渠道结果未知，原交付继续锁定且必须先由平台对账；禁止重试、重复申请或承诺退款结果。";
-        else if (refund.failure_class === "permanent")
-            instruction = "先告诉用户渠道明确拒绝本次退款，当前不能承诺退款成功；不要重试，请用户联系平台支持。";
-        else
-            instruction = "先告诉用户退款没有正常完成，当前不能承诺退款成功；不要重试或重复申请，请用户联系平台支持。";
-    }
-    return {
-        status,
-        result: {
-            refund_request_id: refund.refund_request_id,
-            order_id: refund.order_id,
-            decision_mode: refund.decision_mode,
-            refund_status: refund.status,
-            consumption_state: refund.consumption_state,
-            ...(refund.failure_class ? { failure_class: refund.failure_class } : {}),
-            access_locked: refund.access_locked,
-            can_cancel: refund.can_cancel,
-        },
-        instruction,
-        next: terminal ? null : { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "跟踪同一退款" },
-        recovery: [],
-    };
-}
 export async function runListRefunds(backend, options) {
     const out = resolveOutput(options.output);
     const response = await backend.listOrderRefunds(options.orderID);
@@ -73,7 +34,7 @@ export async function runListRefunds(backend, options) {
                 : "该订单没有退款记录；确认用户确实要求退款后再创建。",
         next: selected
             ? { command: `itpay refund get ${selected.refund_request_id} --json`, reason: active ? "读取活跃退款" : "读取最新退款" }
-            : { command: `itpay refund create --order ${options.orderID} --json`, reason: "为该订单创建退款" },
+            : null,
         recovery: [],
     };
     writeCommandEnvelope(envelope, {
@@ -96,13 +57,13 @@ export async function runGetRefund(backend, refundID, options = {}) {
 export async function runCancelRefund(backend, refundID, reason, options = {}) {
     const refund = await backend.cancelRefund(refundID, reason?.trim() || "buyer_cancelled");
     const envelope = {
-        status: "cancelled",
+        status: refund.status,
         result: {
             refund_request_id: refund.refund_request_id,
             order_id: refund.order_id,
             access_locked: refund.access_locked,
         },
-        instruction: "退款已取消；如需交付，重新进入订单并取得新的授权。",
+        instruction: refund.status === "cancelled" ? "Backend确认退款已取消；如需交付，重新进入原订单核对当前权限，旧grant不自动复活；后端要求时取得新的授权。" : "Backend未确认取消；按返回的退款权威状态核对原订单，不重复提交取消。",
         next: { command: `itpay order ${refund.order_id} --json`, reason: "确认订单访问状态" },
         recovery: [],
     };
@@ -110,36 +71,30 @@ export async function runCancelRefund(backend, refundID, reason, options = {}) {
 }
 export async function runWatchRefund(backend, refundID, options = {}) {
     const intervalSeconds = options.intervalSeconds ?? 2;
-    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    const timeoutSeconds = options.timeoutSeconds ?? 20;
     if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1)
         throw new Error("--interval must be at least 1 second");
     if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)
         throw new Error("--timeout must be a positive number");
     const deadline = Date.now() + timeoutSeconds * 1000;
     let refund;
+    let initialState;
     for (;;) {
         refund = await backend.getRefund(refundID);
-        if (["succeeded", "failed", "cancelled", "rejected"].includes(refund.status)) {
+        const state = JSON.stringify([refund.status, refund.decision_mode, refund.failure_class, refund.access_locked, refund.can_cancel]);
+        if (["succeeded", "failed", "cancelled", "rejected"].includes(refund.status) || refund.decision_mode === "manual" || refund.failure_class === "outcome_unknown" || (initialState !== undefined && state !== initialState)) {
             writeRefundEnvelope(refundStateEnvelope(refund, "watch_complete"), options);
             return;
         }
+        initialState ??= state;
         const remaining = deadline - Date.now();
         if (remaining <= 0)
             break;
         await new Promise((resolve) => setTimeout(resolve, Math.min(intervalSeconds * 1000, remaining)));
     }
-    writeRefundEnvelope({
-        status: "watch_timeout",
-        result: {
-            refund_request_id: refund.refund_request_id,
-            last_status: refund.status,
-            access_locked: refund.access_locked,
-            can_cancel: refund.can_cancel,
-        },
-        instruction: "先告诉用户退款仍在处理，Timeout 只表示本次等待结束，并不表示退款失败；稍后继续跟踪同一退款，不要重复申请或承诺结果。",
-        next: { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "恢复轮询" },
-        recovery: [],
-    }, options);
+    const latest = refundStateEnvelope(refund, "watch_timeout");
+    writeRefundEnvelope({ ...latest, result: { ...latest.result, last_status: refund.status, wait_ended: true },
+        instruction: `本次等待结束，并不表示退款失败。${latest.instruction} 稍后按需读取同一退款，不自动重启等待，不要重复申请。` }, options);
 }
 function writeRefundEnvelope(envelope, options) {
     writeCommandEnvelope(envelope, {
@@ -148,3 +103,4 @@ function writeRefundEnvelope(envelope, options) {
         plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
     });
 }
+export { refundStateEnvelope } from "../services/shared/refund.js";

package/dist/src/commands/services/actions.js

@@ -0,0 +1,133 @@
+import { serviceAdapter } from "../../services/registry.js";
+import { CommandContractError, writeCommandEnvelope } from "../../services/shared/envelope.js";
+import { normalizeServiceActionStatus, paidContinuation, serviceAllowedActionCommand, purchaseConfirmationInstruction, actionInputError } from "../../services/shared/platform.js";
+import { servicesNextEnvelope } from "../../services/presentation.js";
+export async function runServicesAction(backend, serviceExecutionID, actionType, input, options = {}) {
+    const selection = await resolveCandidateSelection(backend, serviceExecutionID, actionType, options);
+    const request = {
+        action_type: actionType,
+        input_snapshot: input,
+    };
+    if (options.actorType)
+        request.actor_type = options.actorType;
+    if (options.actorID)
+        request.actor_id = options.actorID;
+    if (options.status)
+        request.status = normalizeServiceActionStatus(options.status, serviceExecutionID);
+    const resultItemID = selection?.resultItemID ?? options.resultItemID;
+    if (resultItemID)
+        request.result_item_id = resultItemID;
+    if (options.requiredBefore)
+        request.required_before = options.requiredBefore;
+    let response;
+    try {
+        response = await backend.recordServiceExecutionAction(serviceExecutionID, request);
+    }
+    catch (error) {
+        // A failed write is never replayed. Only the locked execution identifies its adapter.
+        try {
+            const model = await backend.getServiceExecution(serviceExecutionID);
+            serviceAdapter(model.execution).actionError(error, serviceExecutionID, actionType);
+        }
+        catch (recoveryError) {
+            if (recoveryError instanceof CommandContractError)
+                throw recoveryError;
+        }
+        throw error;
+    }
+    if (actionType === "approve_purchase" && "status" in response && response.status === "approved") {
+        const quoteID = typeof input.service_quote_lock_id === "string" ? input.service_quote_lock_id : "";
+        writeCommandEnvelope({
+            status: "purchase_preparation_approved",
+            result: { service_execution_id: serviceExecutionID, evidence_source: "agent_reported", scope: "prepare_checkout", service_quote_lock_id: quoteID },
+            instruction: "已记录同范围的准备付款入口批准；这是Agent报告的真实会话同意，不是已付款或出票。继续使用本报价；条件未变不重复询问，官方页实际支付仍由用户完成。",
+            next: quoteID ? { command: `itpay cart add --quote ${quoteID} --json`, reason: "加入本次已批准报价，准备同一个付款入口" } : null,
+            recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取原执行与付款状态，不重新购买" }],
+        }, { ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}), ...(options.output ? { output: options.output } : {}) });
+        return;
+    }
+    if ("state" in response) {
+        const updated = await backend.getServiceExecution(serviceExecutionID);
+        const envelope = servicesNextEnvelope(updated);
+        envelope.result = {
+            ...envelope.result,
+            planning_action: { action_id: response.action_id, state: response.state, replayed: response.replayed },
+        };
+        writeCommandEnvelope(envelope, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
+    if (selection && actionType === "select_candidate" && response.status === "approved") {
+        const updated = await backend.getServiceExecution(serviceExecutionID);
+        const preferred = updated.allowed_actions?.[0];
+        const continuation = preferred?.type === "prepare_quote"
+            ? paidContinuation(updated, preferred, {})
+            : null;
+        const next = continuation?.next ?? (preferred ? serviceAllowedActionCommand(updated, preferred) : null);
+        writeCommandEnvelope({
+            status: "candidate_selected",
+            result: {
+                service_execution_id: response.service_execution_id,
+                candidate: { rank: selection.rank, title: selection.title },
+                ...(continuation ? { checkout: continuation.checkout } : {}),
+            },
+            instruction: continuation
+                ? purchaseConfirmationInstruction("candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose, selection.title)
+                : "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
+            next,
+            recovery: [{
+                    command: `itpay services next ${response.service_execution_id} --json`,
+                    reason: "重新读取服务端允许的动作",
+                }],
+        }, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
+    writeCommandEnvelope({
+        status: "action_recorded",
+        result: {
+            service_execution_id: response.service_execution_id,
+            action_type: response.action_type,
+            action_status: response.status,
+            evidence_source: "agent_reported",
+            reported_actor_type: response.actor_type,
+        },
+        instruction: "动作已记录（Agent转述；actor_type并非官方页面真人确认的证明）。读取服务端计算的新状态；不要自行假设下一 capability。",
+        next: {
+            command: `itpay services next ${response.service_execution_id} --json`,
+            reason: "取得更新后的首选动作",
+        },
+        recovery: [],
+    }, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+    });
+}
+export async function resolveCandidateSelection(backend, serviceExecutionID, actionType, options) {
+    if (options.candidateRank === undefined)
+        return undefined;
+    if (actionType !== "select_candidate") {
+        throw actionInputError(serviceExecutionID, "--candidate is only valid with --action select_candidate");
+    }
+    if (options.resultItemID) {
+        throw actionInputError(serviceExecutionID, "--candidate cannot be combined with --result-item");
+    }
+    if (!Number.isInteger(options.candidateRank) || options.candidateRank < 1) {
+        throw actionInputError(serviceExecutionID, "--candidate must be a positive integer result rank");
+    }
+    const execution = await backend.getServiceExecution(serviceExecutionID);
+    const currentItems = execution.current_result_items ?? [];
+    const result = currentItems.find((item) => item.rank === options.candidateRank);
+    if (!result) {
+        throw actionInputError(serviceExecutionID, `candidate ${options.candidateRank} is not available on service execution ${serviceExecutionID}`, "candidate_not_found");
+    }
+    return {
+        resultItemID: result.service_capability_result_item_id,
+        rank: result.rank,
+        title: result.display_title,
+    };
+}

package/dist/src/commands/services/commerce.js

@@ -0,0 +1,197 @@
+import { assertCheckoutPayable } from "../checkout_handoff.js";
+import { serviceAdapter } from "../../services/registry.js";
+import { HttpError } from "../../client/http.js";
+import { validateContext } from "../../state/client_context.js";
+import { dispatchRender } from "../../render/index.js";
+import { ensureIdeImageAttach } from "../../render/ide.js";
+import { shouldPrepareLocalCheckoutImage } from "../../render/checkout_handoff.js";
+import { localizeCardURL, normalizeCardLocale } from "../../render/locale.js";
+import { platformKeyForHost } from "../../render/plan.js";
+import { renderTerminalQR } from "../../render/qr.js";
+import { buildCheckoutQRPlan } from "../../render/checkout_plan.js";
+import { CommandContractError, writeCommandEnvelope, plainValueLines } from "../../services/shared/envelope.js";
+import { missingRequiredInput, checkoutCommand, formatInputOptions, tokenizedCheckoutURL, absolutePublicURL, fallbackCardURL, fallbackCardPNGURL, buildServicesCheckoutEnvelope, quoteCommand, formatMoney } from "../../services/shared/platform.js";
+export async function runServicesCheckout(backend, config, serviceExecutionID, capabilityID, options = {}) {
+    const host = options.host ?? "terminal";
+    const contextError = validateContext(host, options.target);
+    if (contextError) {
+        throw new CommandContractError(contextError.code, contextError.message, "从当前可信会话上下文补齐 Host/target；本次未创建 Checkout。", []);
+    }
+    const deliveryContact = {
+        ...(options.deliveryContact ?? {}),
+        ...(options.email ? { email: options.email } : {}),
+    };
+    if (!options.resume && !capabilityID) {
+        const model = await backend.getServiceExecution(serviceExecutionID);
+        capabilityID = model.workflow_entry?.capability_id;
+    }
+    if (!options.resume && !capabilityID) {
+        throw new CommandContractError("capability_required", "--capability is required when creating a service checkout", "使用当前 Service Execution 返回的付费 capability；恢复已有 Checkout 时改用 --resume。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前允许的付费 capability" }]);
+    }
+    if (!options.resume) {
+        const readModel = await backend.getServiceExecution(serviceExecutionID);
+        const capability = readModel.capabilities.find((item) => item.capability_id === capabilityID);
+        if (!capability || !capability.requires_payment) {
+            throw new CommandContractError("capability_not_checkoutable", `capability ${capabilityID} is not available for checkout on service execution ${serviceExecutionID}`, "只为当前 Service Execution 返回的 requires_payment capability 创建 Checkout。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前允许的下一步" }]);
+        }
+        if (readModel.checkout_bindings.length === 0 && !readModel.actions.some(action => action.action_type === "approve_purchase" && action.status === "approved")) {
+            await runServicesQuote(backend, serviceExecutionID, capability.capability_id, options.lockedInput ?? {}, options);
+            return;
+        }
+        const lockedInput = options.lockedInput ?? {};
+        const missingInput = missingRequiredInput(capability.input_schema, lockedInput);
+        if (missingInput.length > 0 && !readModel.workflow_entry && readModel.execution.next_action !== "create_checkout") {
+            throw new CommandContractError("capability_input_invalid", `missing required capability input: ${missingInput.join(", ")}`, "补齐付费 capability 的 required_input；本次没有创建 quote、Checkout 或订单。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: checkoutCommand(serviceExecutionID, capability, lockedInput), required_input: missingInput, executable: false } });
+        }
+        if (capability.delivery_email_required && readModel.workflow_entry?.capability_id !== capability.capability_id && String(deliveryContact.email ?? "").trim() === "") {
+            throw new CommandContractError("delivery_email_required", "delivery email is required before creating this service checkout", "该 capability 的交付链接会发送到用户邮箱；先向用户说明用途并询问邮箱，不要代填。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: `itpay services checkout ${serviceExecutionID} --capability ${capability.capability_id}${formatInputOptions(lockedInput)} --email <email> --json`, required_input: ["email"], executable: false } });
+        }
+    }
+    let response;
+    try {
+        response = await backend.createServiceExecutionCheckout(serviceExecutionID, {
+            ...(capabilityID ? { capability_id: capabilityID } : {}),
+            ...(Object.keys(deliveryContact).length > 0 ? { delivery_contact: deliveryContact } : {}),
+            ...(options.lockedInput && Object.keys(options.lockedInput).length > 0 ? { locked_input: options.lockedInput } : {}),
+            ...(options.resume ? { resume: true } : {}),
+        });
+    }
+    catch (error) {
+        if (error instanceof HttpError && error.code === "purchase_approval_required") {
+            throw new CommandContractError(error.code, error.message, "先读当前报价及完整范围模板。沿用覆盖同条件的真实批准；缺少哪部分才补哪部分，不把候选选择当作价格同意，也不代付。", [{ command: capabilityID ? `itpay services quote ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(options.lockedInput ?? {})} --json` : `itpay services next ${serviceExecutionID} --json`, reason: "读取同一执行的当前批准范围，不新建购买" }]);
+        }
+        throw error;
+    }
+    const checkout = response.checkout;
+    const authoritative = checkout.display_token ? await backend.getCheckoutPresentation(checkout.checkout.checkout_id, checkout.display_token) : undefined;
+    assertCheckoutPayable(checkout, authoritative, response.cart.cart_id, serviceExecutionID);
+    if (authoritative)
+        response.cart.items = authoritative.items;
+    const checkoutID = checkout.checkout.checkout_id;
+    const displayToken = checkout.display_token;
+    const locale = normalizeCardLocale(options.locale);
+    const checkoutURL = tokenizedCheckoutURL(checkout.checkout_url, displayToken, checkout.qr_payload);
+    const cardURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_url ?? fallbackCardURL(config.baseURL, checkoutID, displayToken)), locale);
+    const cardPNGURL = localizeCardURL(absolutePublicURL(config.baseURL, checkout.card_png_url ?? checkout.qr_png_url ?? fallbackCardPNGURL(config.baseURL, checkoutID, displayToken)), locale);
+    let itineraryTitle;
+    let itinerary;
+    try {
+        const booking = await backend.getServiceExecution(serviceExecutionID);
+        ({ itinerary, itineraryTitle } = await serviceAdapter(booking.execution).checkout(backend, booking, checkoutID, displayToken));
+    }
+    catch {
+        // Checkout already exists; a display-only title lookup cannot hide its official handoff.
+    }
+    const plan = buildCheckoutQRPlan({
+        localSimulation: backend.localSimulation,
+        host,
+        checkoutID,
+        checkoutURL,
+        cardURL,
+        displayToken,
+        qrPayload: checkout.qr_payload,
+        qrPNGURL: cardPNGURL,
+        nextAction: checkout.checkout.next_action,
+        orderItems: response.cart.items.map((item) => ({
+            title: itineraryTitle || item.title,
+            quantity: item.quantity,
+            amountMinor: item.amount_minor,
+            currency: item.currency,
+        })),
+        orderCurrency: checkout.checkout.currency,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
+        locale,
+    });
+    options.persistHandoff?.({
+        serviceExecutionID,
+        cartID: response.cart.cart_id,
+        checkoutID,
+        displayToken,
+        checkoutURL,
+    });
+    const platform = platformKeyForHost(plan.host);
+    if (!options.jsonOutput && (platform === "telegram" || platform === "feishu" || platform === "lark")) {
+        await dispatchRender(plan, {
+            host,
+            ...(options.target ? { target: options.target } : {}),
+            ...(options.qrFormat ? { qrFormat: options.qrFormat } : {}),
+            ...(options.qrFilePath ? { qrFilePath: options.qrFilePath } : {}),
+            ...(options.output ? { output: options.output } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+            baseURL: config.baseURL,
+        });
+        return;
+    }
+    if (shouldPrepareLocalCheckoutImage(platform)) {
+        await ensureIdeImageAttach(plan, {
+            enabled: config.ideImageAttach,
+            ...(config.baseURL ? { baseURL: config.baseURL } : {}),
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        });
+    }
+    const envelope = buildServicesCheckoutEnvelope(response, checkoutURL, plan, options.agentType, options.target);
+    if (itinerary) {
+        envelope.result = { ...envelope.result, itinerary };
+        envelope.instruction = "整程一次付款，各段分别出票；展示入口不等于付款，付款成功不等于全部出票。" + envelope.instruction;
+    }
+    const plainResult = plainValueLines(envelope.result);
+    if (!options.jsonOutput && platform === "terminal") {
+        plainResult.push("qr:", await renderTerminalQR(checkoutURL, options.qrFormat ?? "terminal"));
+    }
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult,
+    });
+}
+export async function runServicesQuote(backend, serviceExecutionID, capabilityID, input, options = {}) {
+    const model = await backend.getServiceExecution(serviceExecutionID);
+    const capability = model.capabilities.find((item) => item.capability_id === capabilityID);
+    if (!capability || !capability.requires_payment) {
+        throw new CommandContractError("capability_not_quoteable", `capability ${capabilityID} is not available for quote on service execution ${serviceExecutionID}`, "只为当前 Service Execution 返回的付费 capability 创建报价。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前合法动作" }]);
+    }
+    const selectionBacked = model.execution.status === "human_action_approved" &&
+        model.allowed_actions?.some((action) => action.type === "prepare_quote" && action.capability_id === capabilityID);
+    const missingInput = missingRequiredInput(capability.input_schema, input);
+    if (missingInput.length > 0 && !selectionBacked && model.workflow_entry?.capability_id !== capability.capability_id) {
+        throw new CommandContractError("capability_input_invalid", `missing required capability input: ${missingInput.join(", ")}`, "补齐付费 capability 输入；本次没有创建 Quote、Cart 或 Checkout。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: quoteCommand(serviceExecutionID, capability, input), required_input: missingInput, executable: false } });
+    }
+    const deliveryContact = {
+        ...(options.deliveryContact ?? {}),
+        ...(options.email ? { email: options.email } : {}),
+    };
+    if (capability.delivery_email_required && model.workflow_entry?.capability_id !== capability.capability_id && String(deliveryContact.email ?? "").trim() === "") {
+        throw new CommandContractError("delivery_email_required", "delivery email is required before preparing this service quote", "交付链接会发送到用户邮箱；说明用途并询问邮箱，不要代填。", [], { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: { command: quoteCommand(serviceExecutionID, capability, input), required_input: ["email"], executable: false } });
+    }
+    const quote = await backend.prepareServiceQuote(serviceExecutionID, {
+        capability_id: capabilityID,
+        ...(Object.keys(deliveryContact).length > 0 ? { delivery_contact: deliveryContact } : {}),
+        ...(Object.keys(input).length > 0 ? { locked_input: input } : {}),
+    });
+    const result = {
+        service_quote_lock_id: quote.service_quote_lock_id,
+        service_execution_id: quote.service_execution_id,
+        capability_id: quote.capability_id,
+        price: formatMoney(quote.amount_minor, quote.currency),
+        ...(quote.purchase_summary ? { purchase_summary: quote.purchase_summary } : {}),
+        expires_at: quote.expires_at,
+        ...(quote.approval_template ? { approval_template: quote.approval_template } : {}),
+    };
+    writeCommandEnvelope({
+        status: "quote_ready",
+        result,
+        instruction: quote.approval_template
+            ? "报价已锁定。先展示服务端商品名称、对象、范围、数量和金额；与用户请求不符时让用户决定，不自称基础报告或换商品。选择候选不是价格同意；模板中的user_approved=false表示尚未记录批准。仅在用户已有真实批准覆盖本范围时改为true并提交，不重复询问同条件已明确同意。用户授权预算时用capped及真实maximum_minor；仅委托准备入口、最终金额在官方页确认时用confirm_on_official_page。不要伪造接受未知金额或条款。"
+            : "报价已锁定当前 Execution 的可信输入和价格；可单独付款，也可与其他独立 Execution 的报价合并。",
+        ...(quote.approval_template ? { interaction: { schema_version: "itpay.interaction.v1", stage: "purchase_approval_required", input_template: { command: `itpay services action ${serviceExecutionID} --action approve_purchase --actor-type agent --status approved --input-json <file> --json`, input: quote.approval_template, required_input: ["file"], executable: false } } } : {}),
+        next: quote.approval_template ? null : {
+            command: `itpay cart add --quote ${quote.service_quote_lock_id} --json`,
+            reason: "加入 canonical Cart",
+        },
+        recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "重新读取当前 Execution 状态" }],
+    }, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: plainValueLines(result),
+    });
+}