@itpay/cli 2.1.33 → 2.1.40

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),
+    });
+}

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

@@ -0,0 +1,418 @@
+import { serviceAdapter, serviceClientFeatures } from "../../services/registry.js";
+import { HttpError } from "../../client/http.js";
+import { HttpTransportError } from "../../client/transport.js";
+import { DeviceLockBusyError, DeviceStateError } from "../../state/device_authority.js";
+import { operationID } from "../../state/config.js";
+import { CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, plainValueLines } from "../../services/shared/envelope.js";
+import { requiredInputFields, missingRequiredInput, stableInput, formatInputOptions, queryText, capabilityPrice, purchaseConfirmationInstruction, checkoutCommand, serviceResultPlainLines, serviceDeliveryMode, journalTaskState, servicesNextPlainResult } from "../../services/shared/platform.js";
+import { servicesNextEnvelope } from "../../services/presentation.js";
+import { executionInputContext, operationInputTemplate } from "../../services/shared/input.js";
+import { runServicesCheckout } from "./commerce.js";
+export async function runServicesStart(backend, serviceID, options = {}) {
+    const host = options.host ?? "terminal";
+    const response = await backend.startServiceExecution({
+        service_id: serviceID,
+        client_context: {
+            host,
+            features: serviceClientFeatures(),
+            ...(options.target ? { target: options.target } : {}),
+            ...(options.clientContext ?? {}),
+        },
+    });
+    if ("overview_only" in response) {
+        writeServiceOverview(response.service_definition, options);
+        return;
+    }
+    if (!serviceAdapter(response.execution).supported) {
+        writeCommandEnvelope({ status: "presentation_contract_unavailable", result: { service_execution_id: response.execution.service_execution_id, service_id: response.execution.service_id, service_contract_version_id: response.execution.service_contract_version_id }, instruction: "当前锁定合同不受支持；保留原执行与已有结果并停止，使用兼容CLI，不猜模式或输入。", next: null, recovery: [] }, options);
+        return;
+    }
+    if (response.workflow_entry) {
+        const guidance = serviceAdapter(response.execution).guidance(response.execution.service_id, response.workflow_entry.input_schema);
+        if (serviceAdapter(response.execution).requiresGuidance(serviceID) && !guidance) {
+            writeCommandEnvelope({ status: "contract_unavailable", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID }, instruction: "当前执行缺少可用输入合同；只读取一次同执行合同，仍缺失则报告系统缺口并停止，不猜缺失字段或旧输入写法。", next: { command: `itpay services get ${response.execution.service_execution_id} --json`, reason: "读取当前执行锁定的输入合同一次" }, recovery: [] }, options);
+            return;
+        }
+        writeCommandEnvelope({
+            status: "input_required",
+            result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema, ...(guidance ? { guidance } : {}) },
+            instruction: serviceAdapter(response.execution).entryInstruction,
+            next: null,
+            interaction: {
+                schema_version: "itpay.interaction.v1",
+                stage: "input_required",
+                input_template: operationInputTemplate(executionInputContext(response.execution), guidance?.input_example ?? serviceAdapter(response.execution).inputTemplate(response.workflow_entry.input_schema), requiredInputFields(response.workflow_entry.input_schema)),
+            },
+            recovery: []
+        }, { ...options });
+        return;
+    }
+    const capability = response.capabilities.find((item) => item.phase === response.execution.phase && !item.requires_payment);
+    const requiredInput = requiredInputFields(capability?.input_schema);
+    const needsInput = requiredInput.length > 0;
+    const command = capability && !needsInput
+        ? `itpay services invoke ${response.execution.service_execution_id} --capability ${capability.capability_id} --json`
+        : `itpay services next ${response.execution.service_execution_id} --json`;
+    const capabilitySummary = capability ? {
+        capability_id: capability.capability_id,
+        required_input: requiredInput,
+        input_schema: capability.input_schema,
+        ...(capability.free_quota_limit !== undefined ? { free_quota_limit: capability.free_quota_limit } : {}),
+    } : null;
+    writeCommandEnvelope({
+        status: "ready",
+        result: {
+            service_execution_id: response.execution.service_execution_id,
+            service_id: response.execution.service_id,
+            phase: response.execution.phase,
+            capability: capabilitySummary,
+        },
+        instruction: capability
+            ? "填写首选 capability 的 required_input；一次只提交当前 execution 所代表的服务意图。" + serviceAdapter(response.execution).locationInstruction(capability.input_schema)
+            : "当前没有可直接调用的 capability；读取服务端下一步，不要猜测 capability。",
+        next: {
+            command,
+            reason: capability && !needsInput ? "执行当前允许的能力" : "读取服务端计算的下一步",
+        },
+        ...(capability && needsInput ? {
+            interaction: {
+                schema_version: "itpay.interaction.v1",
+                stage: "input_required",
+                input_template: {
+                    command: `itpay services invoke ${response.execution.service_execution_id} --capability ${capability.capability_id}${requiredInput.map((field) => ` --input ${field}=<value>`).join("")} --json`,
+                    required_input: requiredInput,
+                    executable: false,
+                },
+            },
+        } : {}),
+        recovery: [],
+    }, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: [
+            `service_execution_id: ${response.execution.service_execution_id}`,
+            `service_id: ${response.execution.service_id}`,
+            `phase: ${response.execution.phase}`,
+            ...(capability ? [
+                `capability: ${capability.capability_id}`,
+                `required_input: ${requiredInput.length > 0 ? requiredInput.join(",") : "none"}`,
+                ...(capability.free_quota_limit !== undefined ? [`free_quota_limit: ${capability.free_quota_limit}`] : []),
+            ] : []),
+        ],
+    });
+}
+export async function runServicesInvoke(backend, config, serviceExecutionID, capabilityID, input, options = {}) {
+    const readModel = await backend.getServiceExecution(serviceExecutionID);
+    const requestedCapability = readModel.capabilities.find((capability) => capability.capability_id === capabilityID);
+    if (!requestedCapability) {
+        throw new CommandContractError("capability_not_found", `capability ${capabilityID} is not available on service execution ${serviceExecutionID}`, "使用 Service Execution 当前返回的 capability_id，不要猜测名称。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前可用 capability" }]);
+    }
+    if (requestedCapability.requires_payment) {
+        throw new CommandContractError("checkout_required", `capability ${capabilityID} requires checkout and cannot be invoked directly`, "付费 capability 不能直接 invoke。不要尝试 quote、cart、buy、checkout 或 pay 作为旁路；只恢复同一 Execution 的当前合法动作。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取同一 Execution 的当前合法动作" }]);
+    }
+    const missingInput = missingRequiredInput(requestedCapability.input_schema, input);
+    if (missingInput.length > 0) {
+        throw new CommandContractError("capability_input_invalid", `missing required capability input: ${missingInput.join(", ")}`, "只补缺失字段到小JSON文件，再提交同一执行；本次尚未调用供应商。", [], { schema_version: "itpay.interaction.v1", stage: "input_required",
+            input_template: { command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID} --input-json <file> --json`,
+                required_input: ["file", ...missingInput], executable: false } });
+    }
+    const idempotencyKey = await operationID(config, `service.invoke:${serviceExecutionID}:${capabilityID}:${stableInput(input)}`);
+    let response;
+    try {
+        response = await backend.invokeServiceCapability(serviceExecutionID, capabilityID, {
+            idempotency_key: idempotencyKey,
+            redacted_summary: input,
+        });
+    }
+    catch (error) {
+        if (!(error instanceof HttpError) || error.code !== "verified_phone_required")
+            throw error;
+        writeCommandEnvelope({
+            status: "human_action_required",
+            result: { service_execution_id: serviceExecutionID, error_code: "verified_phone_required" },
+            instruction: "需要在官方页面完成手机号验证后当前执行才能继续。运行 itpay auth login 打开官方登录页，完成手机号验证并绑定本设备后重试原命令；CLI 不接收手机号或验证码。",
+            next: { command: "itpay auth login --json", reason: "完成官方手机号验证并绑定当前设备" },
+            recovery: [{ command: `itpay services invoke ${serviceExecutionID} --capability ${capabilityID}${formatInputOptions(input)} --json`, reason: "仅在完成手机号验证与设备绑定后重试" }],
+        }, { ...options, plainResult: ["手机号验证：itpay auth login"] });
+        return;
+    }
+    const envelope = invokedEnvelope(response, requestedCapability, readModel.capabilities, input);
+    writeCommandEnvelope(envelope.value, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: envelope.plainResult,
+    });
+}
+export function invokedEnvelope(response, requestedCapability, capabilities, input) {
+    if (response.execution_request_id) {
+        const id = response.execution.service_execution_id;
+        return { value: { status: "running", result: { service_execution_id: id, execution_request_id: response.execution_request_id },
+                instruction: "查询已排队或正在运行。告知用户稍候，只读取同一任务的状态；不要重新发起查询，也不要把暂未返回结果说成没有车。",
+                next: { command: `itpay services next ${id} --json`, reason: "稍后读取同一查询结果" }, recovery: [] },
+            plainResult: ["status: running", `service_execution_id: ${id}`] };
+    }
+    const items = response.result_items.map((item) => ({
+        rank: item.rank,
+        title: item.display_title,
+        safe_payload: item.safe_payload,
+    }));
+    const quota = response.effective_quota
+        ? { remaining: response.effective_quota.remaining, limit: response.effective_quota.limit }
+        : undefined;
+    const baseResult = {
+        service_execution_id: response.execution.service_execution_id,
+        capability_id: requestedCapability.capability_id,
+        query: input,
+        items,
+        ...(quota ? { quota } : {}),
+    };
+    const businessProjection = serviceAdapter(response.execution).invocation(response, requestedCapability, input, items.length);
+    if (businessProjection?.early)
+        return businessProjection.early;
+    if (businessProjection?.catalog)
+        baseResult.catalog = businessProjection.catalog;
+    let status = items.length > 0 ? "result_ready" : "no_result";
+    let instruction = items.length > 0
+        ? "用编号、名称和可公开字段向用户说明候选；若候选列表已满足目标就停止。只有用户明确选择并希望继续时，才提交对应编号；不要向用户提及 safe_payload、Execution 或内部 ID。"
+        : `没有找到与“${queryText(input)}”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。`;
+    if (businessProjection?.instruction)
+        instruction = businessProjection.instruction;
+    let next = null;
+    if (response.effective_quota?.exhausted) {
+        status = "quota_exhausted";
+        instruction = "免费额度已用完且本次没有调用 Provider。当前没有可购买的 continuation；只读取同一 Execution 的服务端恢复方向。";
+        const checkoutAction = response.next_actions?.find((action) => action.kind === "create_checkout");
+        const checkoutCapability = capabilities.find((capability) => capability.capability_id === checkoutAction?.capability_id);
+        if (checkoutCapability) {
+            baseResult.checkout = {
+                capability_id: checkoutCapability.capability_id,
+                ...(checkoutCapability.price_amount_minor !== undefined && checkoutCapability.price_currency ? {
+                    price: { amount_minor: checkoutCapability.price_amount_minor, currency: checkoutCapability.price_currency },
+                } : {}),
+                delivery_email_required: checkoutCapability.delivery_email_required,
+            };
+            const price = capabilityPrice(checkoutCapability);
+            instruction = purchaseConfirmationInstruction("quota_exhausted", price, checkoutCapability.delivery_email_required, checkoutCapability.delivery_email_purpose);
+            next = {
+                command: checkoutCommand(response.execution.service_execution_id, checkoutCapability, input),
+                reason: `仅在用户明确同意支付 ${price} 后执行；否则停止`,
+            };
+        }
+        else {
+            next = {
+                command: `itpay services next ${response.execution.service_execution_id} --json`,
+                reason: "读取服务端提供的付费恢复入口",
+            };
+        }
+    }
+    else if (items.length > 0 && requestedCapability.requires_human_action) {
+        next = null;
+    }
+    else if (items.length === 0) {
+        next = null;
+    }
+    const interaction = items.length > 0 && requestedCapability.requires_human_action
+        ? {
+            schema_version: "itpay.interaction.v1",
+            stage: "query_results_ready",
+            input_template: {
+                command: `itpay services action ${response.execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
+                required_input: ["rank"],
+                executable: false,
+            },
+        }
+        : undefined;
+    if (businessProjection?.suffix)
+        instruction += businessProjection.suffix;
+    return {
+        value: { status, result: baseResult, instruction, next, recovery: [], ...(interaction ? { interaction } : {}) },
+        plainResult: serviceResultPlainLines(baseResult),
+    };
+}
+export async function runServicesGet(backend, serviceExecutionID, options = {}) {
+    const response = await backend.getServiceExecution(serviceExecutionID);
+    const execution = response.execution;
+    const timeline = response.events.slice(-20).map((event) => ({
+        sequence: event.sequence,
+        step: event.type,
+        status: event.status,
+        phase: event.phase,
+        ...(event.capability_id ? { capability_id: event.capability_id } : {}),
+        occurred_at: event.occurred_at,
+    }));
+    const deliveryMode = serviceDeliveryMode(response);
+    const lockedRefund = response.refunds.find((refund) => refund.access_locked);
+    const nextState = servicesNextEnvelope(response);
+    const result = {
+        ...nextState.result,
+        service_execution_id: execution.service_execution_id,
+        service_id: execution.service_id,
+        status: execution.status,
+        phase: execution.phase,
+        ...(execution.current_capability_id ? { current_capability_id: execution.current_capability_id } : {}),
+        updated_at: execution.updated_at,
+        timeline,
+        ...(response.workflow ? { workflow: response.workflow } : {}),
+        ...serviceAdapter(response.execution).extraFacts(response),
+        ...(response.events.length > timeline.length ? { timeline_truncated: true } : {}),
+        ...(deliveryMode ? { delivery_mode: deliveryMode } : {}),
+        ...(lockedRefund ? {
+            access_locked: true,
+            refund: { refund_request_id: lockedRefund.refund_request_id, status: lockedRefund.status },
+        } : {}),
+    };
+    const envelope = {
+        status: nextState.status,
+        result,
+        instruction: nextState.instruction,
+        next: nextState.next,
+        ...(nextState.interaction ? { interaction: nextState.interaction } : {}),
+        ...(nextState.communication ? { communication: nextState.communication } : {}),
+        ...(nextState.handoff ? { handoff: nextState.handoff } : {}),
+        recovery: nextState.recovery.filter(action => action.command !== `itpay services get ${serviceExecutionID} --json`),
+    };
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: plainValueLines(envelope.result),
+    });
+}
+export function shouldWaitForServiceResult(model) {
+    if (model.current_delivery || isTerminalServiceExecutionStatus(model.execution.status))
+        return false;
+    const adapter = serviceAdapter(model.execution);
+    if (!adapter.supported)
+        return false;
+    const wait = adapter.shouldWait(model);
+    if (wait !== undefined)
+        return wait;
+    return ["queued", "running", "delivery"].includes(model.workflow?.status ?? "");
+}
+export async function runServicesNext(backend, serviceExecutionID, options = {}) {
+    const started = Date.now();
+    const until = started + (options.timeoutSeconds ?? 0) * 1000;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
+    let response = await backend.getServiceExecution(serviceExecutionID, options.sinceSnapshot ? { sinceSnapshot: options.sinceSnapshot } : {});
+    while (shouldWaitForServiceResult(response) && Date.now() < until) {
+        await sleep(options.pollIntervalMS ?? Math.max(1500, serviceAdapter(response.execution).pollAfter(response)));
+        response = await backend.getServiceExecution(serviceExecutionID, options.sinceSnapshot ? { sinceSnapshot: options.sinceSnapshot } : {});
+    }
+    const envelope = servicesNextEnvelope(response);
+    if (shouldWaitForServiceResult(response) && options.timeoutSeconds) {
+        envelope.result = { ...envelope.result, waited_seconds: Math.round((Date.now() - started) / 1000), wait_timed_out: true };
+        envelope.next = { command: `itpay services next ${serviceExecutionID} --timeout 120 --json`, reason: "稍后继续等待同一任务；不重新提交查询" };
+    }
+    journalTaskState(serviceExecutionID, envelope, options.env ?? process.env);
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult: servicesNextPlainResult(envelope.result),
+    });
+}
+export async function runServicesRun(backend, config, serviceID, input, options = {}) {
+    let id = options.executionID;
+    let adapter = serviceAdapter({ service_id: serviceID, service_contract_version_id: "" });
+    let inputContext = { serviceID, operationID: options.operationID, executionID: options.executionID, continuation: options.continuation };
+    try {
+        if (!id) {
+            const started = await backend.startServiceExecution({
+                service_id: serviceID,
+                ...(options.operationID ? { operation_id: options.operationID } : {}),
+                ...(options.continuation ? { continuation: options.continuation } : {}),
+                client_context: { host: options.host ?? "terminal", features: serviceClientFeatures(), ...(options.target ? { target: options.target } : {}) },
+                ...(input !== undefined ? { input } : {}),
+            });
+            if ("overview_only" in started) {
+                writeServiceOverview(started.service_definition, options);
+                return;
+            }
+            id = started.execution.service_execution_id;
+            if (!started.workflow_entry) {
+                await runServicesNext(backend, id, options);
+                return;
+            }
+        }
+        let model = await backend.getServiceExecution(id);
+        adapter = serviceAdapter(model.execution);
+        if (model.execution.public_binding)
+            inputContext = { ...inputContext, ...executionInputContext(model.execution), ...(options.continuation ? { continuation: options.continuation } : {}) };
+        if (model.execution.service_id !== serviceID && model.execution.public_binding?.public_service_id !== serviceID)
+            throw new Error("execution belongs to another service");
+        if (options.operationID && model.execution.public_binding?.operation_id !== options.operationID)
+            throw new Error("execution belongs to another operation");
+        if (!model.workflow_entry || (input === undefined && !model.workflow)) {
+            await runServicesNext(backend, id, options);
+            return;
+        }
+        if (!serviceAdapter(model.execution).supported) {
+            writeCommandEnvelope(servicesNextEnvelope(model), options);
+            return;
+        }
+        if (isTerminalServiceExecutionStatus(model.execution.status)) {
+            // A restored terminal purchase cannot advance or obtain a new checkout.
+            writeCommandEnvelope(servicesNextEnvelope(model), options);
+            return;
+        }
+        if (input !== undefined) {
+            model = await backend.advanceServiceExecution(id, input, `workflow-input:${id}`);
+        }
+        else if (model.workflow?.status === "quota_paused") {
+            model = await backend.advanceServiceExecution(id, undefined, `workflow-resume:${id}`);
+        }
+        const until = Date.now() + (options.timeoutSeconds ?? 120) * 1000;
+        const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
+        const paid = () => model.payment_bindings.some((binding) => binding.status === "payment_verified") || model.checkout_bindings.some((binding) => binding.status === "payment_verified");
+        // A planning projection can exist before any usable result or user action.
+        // Keep the existing bounded wait until there is something to hand over.
+        while ((["queued", "running", "delivery"].includes(model.workflow?.status ?? "") || (model.workflow?.status === "payment" && paid())) && shouldWaitForServiceResult(model) && Date.now() < until) {
+            await sleep(options.pollIntervalMS ?? 1500);
+            model = await backend.getServiceExecution(id);
+        }
+        if (model.refunds.some(refund => refund.access_locked)) {
+            await runServicesNext(backend, id, options);
+            return;
+        }
+        if (model.workflow?.status === "payment" && !paid()) {
+            await runServicesCheckout(backend, config, id, model.workflow_entry?.capability_id, {
+                ...options,
+                ...(config.agentType ? { agentType: config.agentType } : {}),
+                resume: model.checkout_bindings.length > 0,
+            });
+            return;
+        }
+        await runServicesNext(backend, id, options);
+    }
+    catch (cause) {
+        if (cause instanceof HttpError && cause.payload?.service_id && cause.payload.service_contract_version_id)
+            adapter = serviceAdapter({ service_id: cause.payload.service_id, service_contract_version_id: cause.payload.service_contract_version_id });
+        if (cause instanceof HttpError && cause.code === "public_operation_invalid")
+            throw new CommandContractError(cause.code, cause.message, "按返回的固定service_definition核对声明操作；购买仍使用原结果详情的完整continuation模板，不改owner/snapshot、不猜operation、不重建原购买。", cause.payload?.service_definition ? [] : [{ command: `itpay services start ${serviceID} --json`, reason: "只读当前公开定义；不创建执行" }], undefined, { service_id: serviceID, ...(cause.payload?.service_definition ? { service_definition: cause.payload.service_definition } : {}), execution_created: false, provider_called: false });
+        if (cause instanceof HttpError && cause.code === "capability_input_invalid") {
+            const schema = cause.payload?.input_schema;
+            const executionID = cause.payload?.service_execution_id ?? id;
+            const errorAdapter = cause.payload?.service_id && cause.payload?.service_contract_version_id ? serviceAdapter({ service_id: cause.payload.service_id, service_contract_version_id: cause.payload.service_contract_version_id }) : adapter;
+            if (!errorAdapter.supported)
+                throw new CommandContractError("presentation_contract_unavailable", cause.message, "当前锁定合同不受此CLI支持；保留原输入和执行并停止，使用兼容CLI，不猜业务或提交修正模板。", [], undefined, { service_id: serviceID, ...(executionID ? { service_execution_id: executionID } : {}), original_error_code: cause.code });
+            throw new CommandContractError(cause.code, cause.message, errorAdapter.inputInstruction, schema ? [] : [{ command: executionID ? `itpay services get ${executionID} --json` : "itpay catalog list --json", reason: "获取当前锁定合同；仍缺合同则停止，不猜旧写法" }], schema ? { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: operationInputTemplate({ ...inputContext, executionID }, errorAdapter.inputTemplate(schema, input), requiredInputFields(schema)) } : undefined, { service_id: serviceID, ...(executionID ? { service_execution_id: executionID } : {}), execution_created: cause.payload?.execution_created ?? Boolean(executionID), ...(typeof cause.payload?.provider_called === "boolean" ? { provider_called: cause.payload.provider_called } : {}), input_errors: cause.payload?.input_errors ?? [cause.message], ...(schema ? { input_schema: schema } : {}) });
+        }
+        adapter.runError(cause, serviceID, id);
+        if (cause instanceof CommandContractError || cause instanceof HttpError || cause instanceof DeviceLockBusyError || cause instanceof DeviceStateError)
+            throw cause;
+        if (!id) {
+            throw new CommandContractError("workflow_start_outcome_unknown", cause instanceof Error ? cause.message : "service creation outcome unknown", "创建服务执行时没有收到完整响应。先查询当前身份可见的执行；不要直接重跑并创建替代执行。", [{ command: "itpay services list --json", reason: "查找可能已经创建的服务执行" }]);
+        }
+        if (cause instanceof HttpTransportError)
+            throw new CommandContractError("workflow_outcome_unknown", cause.message, "未收到完整响应；只读同一执行的权威事实，不重放写操作或创建替代执行。", [{ command: `itpay services next ${id} --json`, reason: "核对同一执行" }]);
+        throw new CommandContractError("workflow_run_failed", cause instanceof Error ? cause.message : "workflow run failed", "保留当前执行并按错误处理，不要重复创建服务执行。", [{ command: `itpay services next ${id} --json`, reason: "读取同一执行的当前事实与恢复动作" }]);
+    }
+}
+export function writeServiceOverview(definition, options) {
+    const adapter = serviceAdapter({ service_id: definition.service_id, service_contract_version_id: definition.definition_version, public_binding: { public_service_id: definition.service_id, service_definition_version: definition.definition_version, operation_id: "overview", adapter_key: definition.adapter_key } });
+    if (!adapter.supported) {
+        writeCommandEnvelope({ status: "presentation_contract_unavailable", result: { service_id: definition.service_id, definition_version: definition.definition_version }, instruction: "当前公开定义不受此CLI支持；保留原任务并停止，使用兼容CLI，不猜操作或输入合同。", next: null, recovery: [] }, options);
+        return;
+    }
+    const operations = definition.operations.map(op => ({ operation_id: op.id, title: op.display_names["zh-CN"], role: op.role, billing_mode: op.billing_mode, requires_continuation: op.requires_continuation ?? false, ...(!op.requires_continuation ? { input_schema: op.input_schema, input_template: operationInputTemplate({ serviceID: definition.service_id, operationID: op.id }, adapter.inputTemplate(op.input_schema), requiredInputFields(op.input_schema)) } : { instruction: "使用已有结果详情返回的完整准备购买模板、输入合同和continuation；不自行拼凭据或重新发现购买服务。" }) }));
+    const result = { service_id: definition.service_id, title: definition.display_names["zh-CN"], definition_version: definition.definition_version, ...(definition.guide ? { guide: `itpay docs show ${definition.guide.topic}` } : {}), operations };
+    writeCommandEnvelope({ status: "service_overview", result, instruction: adapter.overviewInstruction(definition.guide?.topic ?? ""), next: definition.guide ? { command: `itpay docs show ${definition.guide.topic}`, reason: "首次操作前读取服务的完整指导" } : null, recovery: [] }, { ...options, plainResult: plainValueLines(result) });
+}