@itpay/cli 2.1.34 → 2.1.40

package/dist/src/services/shared/pagination.js

@@ -0,0 +1,28 @@
+import { CommandContractError, writeCommandEnvelope } from "./envelope.js";
+// Bound the final qualified output by whole saved rows; the cursor follows the emitted rows.
+export function writeSavedPage(envelope, options, key, offset, continuation, updateMetadata) {
+    const result = envelope.result ?? {};
+    const rows = result[key];
+    if (!Array.isArray(rows))
+        throw new Error("saved page has no rows");
+    const bound = (offset === 0 ? 12 : 32) * 1024;
+    const render = (output) => writeCommandEnvelope(envelope, { ...options, output });
+    if (!options.all) {
+        for (;;) {
+            let text = "";
+            render(value => { text += value; });
+            if (Buffer.byteLength(text, "utf8") <= bound)
+                break;
+            if (rows.length <= 1) {
+                throw new CommandContractError("saved_row_too_large", "saved row exceeds the readable page limit", "这条已保存记录超过当前页面大小；事实仍保留，请读取该条详情。", rows[0]?.detail?.command ? [rows[0].detail] : []);
+            }
+            rows.pop();
+            result.truncated_reason = "cli_output_byte_budget";
+            result.count = rows.length;
+            updateMetadata(result, rows.length);
+            result.next_offset = offset + rows.length;
+            envelope.next = continuation(offset + rows.length);
+        }
+    }
+    writeCommandEnvelope(envelope, options);
+}

package/dist/src/services/shared/platform.js

@@ -0,0 +1,365 @@
+import { taskJournalPath } from "../../state/config.js";
+import { TaskJournal } from "../../state/task_journal.js";
+import { buildCheckoutHandoff } from "../../render/checkout_handoff.js";
+import { buildAgentChatHandoff } from "../../render/markdown.js";
+import { platformKeyForHost } from "../../render/plan.js";
+import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, shellArgument, plainValueLines } from "./envelope.js";
+// AUTH04: record the pause point of each Service Execution so a later
+// `itpay auth login` can resume the SAME task. Ids/stage/resume command only —
+// no chat content, PII or credentials. Best-effort: journaling never breaks
+// a command.
+export function journalTaskState(serviceExecutionID, envelope, env) {
+    try {
+        const journal = new TaskJournal(taskJournalPath(env));
+        const serviceID = typeof envelope.result?.service_id === "string" ? envelope.result.service_id : undefined;
+        journal.observe(serviceExecutionID, envelope.status, serviceID ? `itpay services run ${serviceID} --execution ${serviceExecutionID} --json` : undefined);
+    }
+    catch {
+        /* local journal is advisory; never fail the envelope */
+    }
+}
+export const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
+export function requiredInputFields(schema) {
+    const required = schema?.required;
+    return Array.isArray(required) ? required.filter((field) => typeof field === "string") : [];
+}
+export function serviceResultPlainLines(result) {
+    return plainValueLines(result);
+}
+export function queryText(input) {
+    const value = Object.values(input).find((item) => typeof item === "string" && item.trim() !== "");
+    return typeof value === "string" ? value : JSON.stringify(input);
+}
+export function missingRequiredInput(schema, input) {
+    return requiredInputFields(schema).filter((field) => {
+        if (!(field in input) || input[field] === null || input[field] === undefined)
+            return true;
+        return typeof input[field] === "string" && String(input[field]).trim() === "";
+    });
+}
+export function checkoutCommand(serviceExecutionID, capability, input, fillMissing = true) {
+    const lockedInput = { ...input };
+    if (fillMissing) {
+        for (const field of missingRequiredInput(capability.input_schema, lockedInput))
+            lockedInput[field] = "<value>";
+    }
+    return `itpay services checkout ${serviceExecutionID} --capability ${capability.capability_id}${formatInputOptions(lockedInput)}${capability.delivery_email_required ? " --email <email>" : ""} --json`;
+}
+export function capabilityPrice(capability) {
+    if (capability.pricing_method !== undefined)
+        return "动态报价（最终金额以锁定报价为准）";
+    return capability.price_amount_minor !== undefined && capability.price_currency
+        ? formatMoney(capability.price_amount_minor, capability.price_currency)
+        : "当前发布价格";
+}
+export function purchaseConfirmationInstruction(context, price, deliveryEmailRequired, deliveryEmailPurpose, candidateTitle = "") {
+    const emailPurpose = deliveryEmailPurposeText(deliveryEmailPurpose);
+    if (context === "quota_exhausted") {
+        return deliveryEmailRequired
+            ? `免费额度已用完，本次没有发送到数据来源，也没有创建付款页面。只向用户说明：继续当前请求需要支付 ${price}，并提供${emailPurpose}；请确认是否购买并提供邮箱。然后停止等待。用户明确同意并提供真实邮箱前，Agent 不执行 next.command，也不创建或尝试其他购买路径。`
+            : `免费额度已用完，本次没有发送到数据来源，也没有创建付款页面。只向用户说明：“继续当前请求需要支付 ${price}，是否购买？”然后停止等待。用户明确同意前，Agent 不执行 next.command，也不创建或尝试其他购买路径。`;
+    }
+    const selected = candidateTitle ? `已选择 ${candidateTitle}。` : "当前候选已经确认。";
+    return deliveryEmailRequired
+        ? `${selected}后续服务尚未购买。只向用户说明：继续购买需要支付 ${price}，并提供${emailPurpose}；请确认是否购买并提供邮箱。然后停止。用户明确同意并提供真实邮箱前，Agent 不执行 next.command，也不创建新的服务或付款页面。`
+        : `${selected}后续服务尚未购买。只向用户说明：“继续购买后续服务需要支付 ${price}，是否购买？”然后停止。用户明确同意前，Agent 不执行 next.command，也不创建新的服务或付款页面。`;
+}
+export function deliveryEmailPurposeText(purpose) {
+    switch (purpose) {
+        case "receipt":
+            return "用于发送订单收据的真实邮箱";
+        case "claim":
+            return "用于发送交付认领链接的真实邮箱";
+        case "receipt_and_claim":
+            return "用于发送订单收据和交付认领链接的真实邮箱";
+        default:
+            return "服务端声明用途的真实邮箱";
+    }
+}
+export function paidContinuation(model, action, input) {
+    if (!action.capability_id)
+        return null;
+    const capability = model.capabilities.find((item) => item.capability_id === action.capability_id && item.requires_payment);
+    if (!capability)
+        return null;
+    const price = capabilityPrice(capability);
+    const stateBacked = model.execution.status === "quota_exhausted" || model.execution.status === "human_action_approved";
+    return {
+        capability,
+        price,
+        checkout: {
+            capability_id: capability.capability_id,
+            ...(capability.price_amount_minor !== undefined && capability.price_currency ? {
+                price: { amount_minor: capability.price_amount_minor, currency: capability.price_currency },
+            } : {}),
+            delivery_email_required: capability.delivery_email_required,
+            ...(capability.delivery_email_purpose ? { delivery_email_purpose: capability.delivery_email_purpose } : {}),
+        },
+        next: {
+            command: checkoutCommand(model.execution.service_execution_id, capability, input, !stateBacked),
+            reason: `仅在用户明确同意支付 ${price}${capability.delivery_email_required ? " 并提供真实邮箱" : ""}后执行；否则停止`,
+        },
+    };
+}
+export function quoteCommand(serviceExecutionID, capability, input) {
+    const lockedInput = { ...input };
+    for (const field of missingRequiredInput(capability.input_schema, lockedInput))
+        lockedInput[field] = "<value>";
+    return `itpay services quote ${serviceExecutionID} --capability ${capability.capability_id}${formatInputOptions(lockedInput)}${capability.delivery_email_required ? " --email <email>" : ""} --json`;
+}
+export function stableInput(input) {
+    return JSON.stringify(Object.fromEntries(Object.entries(input).sort(([left], [right]) => left.localeCompare(right))));
+}
+export function formatInputOptions(input) {
+    return Object.entries(input)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => String(value) === "<value>"
+        ? ` --input ${key}=<value>`
+        : ` --input ${shellArgument(`${key}=${typeof value === "object" && value !== null ? JSON.stringify(value) : String(value)}`)}`)
+        .join("");
+}
+export function actionInputError(serviceExecutionID, message, code = "service_action_invalid") {
+    return new CommandContractError(code, message, code === "candidate_not_found"
+        ? "当前 rank 不存在或当前候选集不可用。不要新建 Execution，不要重新 invoke，不要构造候选 ID；只恢复同一 Execution 当前仍然有效的候选。"
+        : "使用当前 safe result 中的合法 action 和 candidate rank；需要人确认时先询问用户。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "重新读取同一 Execution 的当前可选动作" }]);
+}
+export function terminalExecutionEnvelope(model) {
+    const execution = model.execution;
+    const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    if (!isTerminalServiceExecutionStatus(execution.status) ||
+        (model.workflow_entry && (currentDelivery || serviceDeliveryMode(model) === "agent_visible_result") && ["completed", "delivery_completed"].includes(execution.status))) {
+        return null;
+    }
+    const paid = model.checkout_bindings.some((binding) => binding.status === "payment_verified") || Boolean(currentDelivery?.order_id);
+    const paidFailure = execution.status === "failed" && paid;
+    return {
+        status: execution.status,
+        result: {
+            service_execution_id: execution.service_execution_id,
+            service_id: execution.service_id,
+            phase: execution.phase,
+            ...(currentDelivery?.order_id ? { order_id: currentDelivery.order_id, aftercare: { optional: true, command: `itpay feedback submit --order ${shellArgument(currentDelivery.order_id)} --json`, reason: "告知原单结果后按需复盘，不猜评分或上传隐私" } } : {}),
+        },
+        instruction: execution.status === "refunded"
+            ? "告诉用户这笔服务已经退款并永久结束。Agent 不重放服务步骤、不创建付款页面或尝试读取旧交付。"
+            : paidFailure
+                ? appendFeedbackPostmortemInstruction("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
+                : "告诉用户本次服务已经结束且没有可继续的交付。Agent 不重放服务步骤或创建付款页面。",
+        next: null,
+        recovery: [
+            ...(paidFailure
+                ? [{
+                        command: currentDelivery?.order_id
+                            ? `itpay order ${currentDelivery.order_id} --json`
+                            : "itpay orders --json",
+                        reason: "恢复同一笔已付款订单及其退款状态",
+                    }]
+                : []),
+            {
+                command: `itpay services events ${execution.service_execution_id} --json`,
+                reason: "仅在需要诊断终止原因时读取事件",
+            },
+        ],
+    };
+}
+export function serviceAllowedActionCommand(model, action) {
+    const executionID = model.execution.service_execution_id;
+    const capability = action.capability_id
+        ? model.capabilities.find((item) => item.capability_id === action.capability_id)
+        : undefined;
+    switch (action.type) {
+        case "invoke_capability": {
+            if (!capability)
+                return null;
+            const input = Object.fromEntries(requiredInputFields(capability.input_schema).map((field) => [field, "<value>"]));
+            return {
+                command: `itpay services invoke ${executionID} --capability ${capability.capability_id}${formatInputOptions(input)} --json`,
+                reason: "执行当前允许的 Agent-visible capability",
+            };
+        }
+        case "select_candidate":
+            return {
+                command: `itpay services action ${executionID} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
+                reason: "仅在用户明确选择后提交当前候选 rank",
+            };
+        case "prepare_quote": {
+            return paidContinuation(model, action, {})?.next ?? null;
+        }
+        case "resume_checkout":
+            return { command: `itpay services checkout ${executionID} --resume --json`, reason: "恢复同一 Checkout，不创建第二笔" };
+        case "wait":
+            return { command: `itpay services next ${executionID} --json`, reason: "等待 durable execution 推进" };
+        case "view_delivery":
+            return { command: `itpay services next ${executionID} --json`, reason: "读取当前交付模式" };
+        default:
+            return null;
+    }
+}
+export function serviceDeliveryMode(model) {
+    const delivery = model.current_delivery ?? model.delivery_bindings.at(-1);
+    const entry = model.capabilities.find(capability => capability.capability_id === model.workflow_entry?.capability_id);
+    if (!delivery && model.workflow?.status === "completed" && entry?.requires_payment === false && !entry.vault_required)
+        return "agent_visible_result";
+    const explicit = String(delivery?.redacted_summary?.delivery_mode ?? "");
+    if (explicit)
+        return explicit;
+    return delivery?.vault_artifact_id ? "vault_artifact" : "";
+}
+export function normalizeGrantStatus(status) {
+    return !status || status === "missing" ? "none" : status;
+}
+export function grantedResultEnvelope(response, orderID) {
+    return {
+        status: "granted_result_ready",
+        result: {
+            service_execution_id: response.service_execution_id,
+            ...(orderID ? { order_id: orderID, aftercare: { optional: true, command: `itpay feedback submit --order ${shellArgument(orderID)} --json`, reason: "交付答复后按需复盘，不猜评分或上传隐私" } } : {}),
+            ...(response.expires_at ? { grant_expires_at: response.expires_at } : {}),
+            granted_fields: Object.keys(response.result),
+            payload: response.result,
+        },
+        instruction: orderID
+            ? appendFeedbackPostmortemInstruction("结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。", "delivered")
+            : "结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。",
+        next: null,
+        recovery: [],
+    };
+}
+export function servicesNextPlainResult(result) {
+    return plainValueLines(result);
+}
+export function parseKeyValueList(values) {
+    const result = {};
+    for (const value of values ?? []) {
+        const index = value.indexOf("=");
+        if (index <= 0) {
+            throw new Error(`invalid --input "${value}", expected key=value`);
+        }
+        result[value.slice(0, index)] = parseValue(value.slice(index + 1));
+    }
+    return result;
+}
+export function collectOption(value, previous = []) {
+    previous.push(value);
+    return previous;
+}
+export function parseValue(value) {
+    // Structured inputs (objects/arrays) are passed as JSON; a string that merely
+    // starts with a JSON delimiter but is not valid JSON stays a string — the
+    // backend schema validates the field type either way.
+    if (value.startsWith("{") || value.startsWith("[")) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value;
+        }
+    }
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(value))
+        return Number(value);
+    return value;
+}
+export function buildServicesCheckoutEnvelope(response, checkoutURL, plan, agentType, target) {
+    const checkout = response.checkout;
+    const platform = platformKeyForHost(plan.host);
+    const amount = formatMoney(checkout.checkout.amount_minor, checkout.checkout.currency);
+    const presentationHandoff = buildCheckoutHandoff({
+        platform,
+        url: plan.linkOnlyURL ?? checkoutURL,
+        mobileUrl: checkoutURL,
+        amount,
+        plan,
+        ...(agentType ? { agentType } : {}),
+        ...(target ? { target } : {}),
+        ...(plan.preferredQRSources[0] ? { qrImageURL: plan.preferredQRSources[0] } : {}),
+        ...(plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath
+            ? { localPath: plan.ideImageAttach.localPath }
+            : {}),
+        ...(platform === "markdown" ? { markdown: buildAgentChatHandoff(plan).markdown } : {}),
+    });
+    return {
+        status: "human_checkout_required",
+        result: {
+            service_execution_id: response.binding.service_execution_id,
+            checkout_id: checkout.checkout.checkout_id,
+            capability_id: checkoutCapabilityID(response),
+            items: plan.orderItems ?? [],
+            amount,
+            ...(checkout.checkout.expires_at ? {
+                // The shared server-owned payable deadline D: refreshing the page or
+                // re-creating a checkout can never extend it; past it the checkout
+                // and pending order are terminally cancelled.
+                payment_deadline_at: checkout.checkout.expires_at,
+            } : {}),
+        },
+        handoff: presentationHandoff.handoff,
+        instruction: presentationHandoff.instruction,
+        next: {
+            command: plan.afterActionCommand ?? `itpay checkout --id ${checkout.checkout.checkout_id} --token ${checkout.display_token} --json`,
+            reason: "仅在用户完成付款操作或要求查询后，读取同一 Checkout 的权威状态",
+        },
+        recovery: [],
+    };
+}
+export function fallbackCardURL(baseURL, checkoutID, displayToken) {
+    const root = baseURL.replace(/\/$/, "");
+    return `${root}/v1/checkouts/${encodeURIComponent(checkoutID)}/card?display_token=${encodeURIComponent(displayToken)}`;
+}
+export function fallbackCardPNGURL(baseURL, checkoutID, displayToken) {
+    return `${fallbackCardURL(baseURL, checkoutID, displayToken)}.png`.replace("/card?", "/card.png?");
+}
+export function checkoutCapabilityID(response, fallback = "") {
+    return response.capability_id || fallback;
+}
+export function absolutePublicURL(baseURL, value) {
+    try {
+        return new URL(value, baseURL.endsWith("/") ? baseURL : `${baseURL}/`).toString();
+    }
+    catch {
+        return value;
+    }
+}
+export function formatMoney(amountMinor, currency) {
+    return `${(amountMinor / 100).toFixed(2)} ${currency}`;
+}
+export function normalizeServiceActionStatus(status, serviceExecutionID) {
+    const normalized = status.trim().toLowerCase();
+    if (!serviceActionStatuses.has(normalized)) {
+        throw actionInputError(serviceExecutionID, `invalid --status "${status}". Supported: pending, approved, rejected, expired, cancelled`);
+    }
+    return normalized;
+}
+export function tokenizedCheckoutURL(checkoutURL, displayToken, qrPayload) {
+    if (qrPayload.trim().length > 0) {
+        return qrPayload;
+    }
+    if (checkoutURL.trim().length === 0 || displayToken.trim().length === 0) {
+        return checkoutURL;
+    }
+    try {
+        const parsed = new URL(checkoutURL);
+        if (!parsed.searchParams.has("display_token")) {
+            parsed.searchParams.set("display_token", displayToken);
+        }
+        return parsed.toString();
+    }
+    catch {
+        const separator = checkoutURL.includes("?") ? "&" : "?";
+        return `${checkoutURL}${separator}display_token=${encodeURIComponent(displayToken)}`;
+    }
+}
+export function publicPurchaseTemplate(value) {
+    if (value === undefined)
+        return undefined;
+    const invalid = () => new CommandContractError("public_operation_contract_invalid", "incomplete public purchase operation", "服务返回的准备购买合同不完整；保留当前快照与已有购买并停止，不能退回旧入口拼接凭据。", [], undefined, { reason: "purchase_contract_missing" });
+    if (typeof value !== "object" || value === null || Array.isArray(value) || !("service_id" in value) || typeof value.service_id !== "string" || !("operation_id" in value) || typeof value.operation_id !== "string" || !("input" in value) || typeof value.input !== "object" || value.input === null || Array.isArray(value.input) || !("continuation" in value))
+        throw invalid();
+    const ref = value.continuation;
+    if (typeof ref !== "object" || ref === null || Array.isArray(ref) || !("service_execution_id" in ref) || typeof ref.service_execution_id !== "string" || !("snapshot_id" in ref) || typeof ref.snapshot_id !== "string")
+        throw invalid();
+    return { command: `itpay services run ${shellArgument(value.service_id)} --operation ${shellArgument(value.operation_id)} --input-json <file> --json`, input_example: { input: value.input, continuation: { service_execution_id: ref.service_execution_id, snapshot_id: ref.snapshot_id } }, executable: false };
+}

package/dist/src/services/shared/refund.js

@@ -0,0 +1,40 @@
+export function refundStateEnvelope(refund, status) {
+    const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
+    let instruction = refund.decision_mode === "manual"
+        ? "先告诉用户退款已进入人工审核，原交付保持冻结；人工审核不等于拒绝，等待服务器决定，不要重复申请或承诺结果。"
+        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不读取交付、不创建授权或重复申请。";
+    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: instruction + " consumption_state是平台交付内容的消费事实，access_locked是交付访问锁；不能据此推断线下服务是否已使用或退款资格。",
+        next: terminal ? null : { command: `itpay refund get ${refund.refund_request_id} --json`, reason: "按需读取同一退款；不自动循环等待" },
+        recovery: [],
+    };
+}

package/dist/src/services/shared/workflow.js

@@ -0,0 +1,28 @@
+import { executionInputContext, operationInputTemplate, serviceInputTemplate } from "./input.js";
+import { requiredInputFields } from "./platform.js";
+export function workflowEnvelope(model) {
+    if (!model.workflow_entry || ["completed", "delivery"].includes(model.workflow?.status ?? ""))
+        return undefined;
+    const id = model.execution.service_execution_id;
+    const code = model.workflow?.error_code;
+    if (["failed", "quota_paused"].includes(model.workflow?.status ?? "") && ["login_required", "rate_limited"].includes(code ?? "")) {
+        const login = code === "login_required";
+        return { status: code, result: { service_execution_id: id, current_step: model.workflow?.current_step, ...(model.quota ? { quota: model.quota } : {}), ...(model.workflow?.dependency ? { dependency: model.workflow.dependency } : {}) }, instruction: login ? "当前账户需要登录；展示官方登录入口后，按返回恢复动作继续同一执行，不重新创建。" : "本执行达到调用额度；尊重服务端恢复时间，只继续同一执行，不自动重查或创建付款。", next: login ? { command: "itpay auth login --json", reason: "登录后恢复同一执行" } : null, recovery: [] };
+    }
+    const action = model.workflow?.human_action;
+    const state = model.workflow?.status ?? "input_required";
+    if (state === "human_action" && action)
+        return {
+            status: "confirmation_required", result: { service_execution_id: id, human_action: action },
+            instruction: "展示本次操作的待确认内容；已有明确同意且目标与版本未变时沿用，只补缺失的真实同意。按完整模板提交同一执行；选择对象不等于购买批准。",
+            next: null, recovery: [], interaction: { schema_version: "itpay.interaction.v1", stage: "confirmation_required", input_template: { command: `itpay services action ${id} --action ${action.action_type} --actor-type human --status approved --input-json <file> --json`, input: serviceInputTemplate(action.input_schema), required_input: ["file", ...requiredInputFields(action.input_schema)], executable: false } },
+        };
+    const inputRequired = state === "input_required";
+    const failed = ["failed", "recovery_required", "cancelled"].includes(state);
+    const dependency = model.workflow?.dependency;
+    return { status: dependency ? "dependency_unavailable" : state, result: { service_execution_id: id, service_id: model.execution.service_id, ...(model.workflow ? { current_step: model.workflow.current_step, workflow_revision: model.workflow.revision, error_code: model.workflow.error_code } : {}), ...(model.workflow?.failure ? { failure: model.workflow.failure } : {}), ...(dependency ? { dependency } : {}), ...(inputRequired ? { input_schema: model.workflow_entry.input_schema } : {}) },
+        instruction: dependency ? "服务返回外部依赖故障；保留原输入及已有结果，只按返回的重试条件恢复。不猜供应商或错误原因，也不要求用户更改业务条件。" : failed ? "本执行未完成；核对返回原因和已有付款事实。没有明确恢复动作时停止，不重建购买。" : inputRequired ? "按当前锁定合同写入完整输入文件，继续同一执行，不猜字段。" : state === "payment" ? "已到准备付款入口步骤；报价与当前范围批准仍需核对，实际付款由用户在官方页面完成。" : "继续读取同一执行的当前状态。",
+        next: failed || inputRequired || dependency ? null : { command: state === "payment" ? `itpay services checkout ${id} --json` : `itpay services next ${id} --json`, reason: "继续同一执行" }, recovery: [],
+        ...(inputRequired ? { interaction: { schema_version: "itpay.interaction.v1", stage: "input_required", input_template: operationInputTemplate(executionInputContext(model.execution), serviceInputTemplate(model.workflow_entry.input_schema, model.workflow?.query_input), requiredInputFields(model.workflow_entry.input_schema)) } } : {}),
+    };
+}

package/dist/src/state/account_auth.js

@@ -1,3 +1,6 @@
+import { HttpError } from '../client/http.js';
+import { HttpTransportError } from '../client/transport.js';
+import { DeviceAuthorizationError, DeviceStateError, DeviceLockBusyError } from './device_authority.js';
 import { createHash } from 'node:crypto';
 import { dirname, resolve } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, rmSync } from 'node:fs';
@@ -38,10 +41,10 @@ export function agentAuth(action, baseURL, backend, env = process.env, fetcher =
 const ACTIVE_SESSION_STAGES = ['created', 'waiting_provider', 'email_verification_required', 'merge_confirmation_required'];
 function stageInstruction(stage) {
     if (stage === 'email_verification_required') {
-        return '钱包授权已完成，官方页还需要完成联系方式验证（邮箱或手机，以页面实际提供的方式为准）。完成后继续原查询，不用重说行程。';
+        return '官方页返回显式或历史身份验证状态；按页面当前要求完成验证。普通登录只需一种有效身份，不要求补齐邮箱和手机。完成后恢复原执行。';
     }
     if (stage === 'merge_confirmation_required') {
-        return '官方页需要用户确认账号合并决定后才能完成登录；不要替用户选择，也不要新建授权请求。';
+        return '官方页需要用户核对两侧账号证明及主账号，再明确确认或取消合并；这不是付款确认。不要替用户同意，不自动重启原服务或授权请求。';
     }
     return '用户仍在官方页面完成登录；保留当前 handoff，不要生成新二维码或新请求。';
 }
@@ -75,12 +78,24 @@ class AuthRequestError extends Error {
 }
 // AUTH03: transport/read uncertainty never maps to "denied" or a new session —
 // the stored session stays on disk and the caller retries the same poll.
-function authStatusUnknown(sessionID) {
+function authStatusUnknown(sessionID, error) {
+    // These errors have definite compatibility/identity/state facts. Let the
+    // command boundary report them rather than turning them into polling.
+    if ((error instanceof HttpError && error.status < 500)
+        || (error instanceof AuthRequestError && error.httpStatus < 500)
+        || error instanceof DeviceAuthorizationError || error instanceof DeviceStateError
+        || error instanceof DeviceLockBusyError)
+        throw error;
+    const failure = error instanceof HttpTransportError
+        ? { category: error.code, attempts: error.attempts }
+        : { category: 'authorization_status_unavailable' };
     return {
         status: 'auth_status_unknown',
-        result: sessionID ? { dashboard_auth_session_id: sessionID } : {},
-        instruction: '读取官方授权状态时遇到网络或服务端临时故障；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。',
-        next: { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 },
+        result: { ...failure, ...(sessionID ? { dashboard_auth_session_id: sessionID } : {}) },
+        instruction: sessionID
+            ? '读取官方授权状态失败；原授权请求已保留。稍后重读同一状态，不要新建授权、不要清除本地登记。'
+            : '本轮账号绑定检查未完成，设备与绑定状态尚未确认；没有保存的授权请求。结束本轮，网络或服务恢复后可重新检查，不发起登录。',
+        next: sessionID ? { command: 'itpay auth status --json', reason: '稍后重读同一授权状态', poll_after_ms: 5000 } : null,
         recovery: [],
     };
 }
@@ -134,7 +149,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 throw error;
             // AUTH03: even the binding-status probe can hit transport failure; the
             // truthful state is "unknown", never an implicit unbound or a fresh login.
-            return authStatusUnknown(undefined);
+            return authStatusUnknown(read(baseURL, env, purpose)?.sessionID, error);
         }
     }
     async function request(path, init = {}) {
@@ -204,7 +219,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                         // remains read-only and still reports the missing old session.
                     }
                     else {
-                        return authStatusUnknown(open.sessionID);
+                        return authStatusUnknown(open.sessionID, error);
                     }
                 }
             }
@@ -280,7 +295,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
         if (error instanceof AuthRequestError && (error.httpStatus === 404 || error.httpStatus === 410)) {
             return sessionGone(env, purpose, baseURL, state.sessionID);
         }
-        return authStatusUnknown(state.sessionID);
+        return authStatusUnknown(state.sessionID, error);
     }
     if (progress.status !== 'completed') {
         if (backend) {
@@ -318,7 +333,7 @@ async function accountAuth(action, baseURL, env, fetcher, backend) {
                 throw error;
             // Binding outcome unknown: keep the session so a retry can still bind
             // the same completed login instead of creating a new one.
-            return authStatusUnknown(state.sessionID);
+            return authStatusUnknown(state.sessionID, error);
         }
     }
     const claimed = await request(`/v1/dashboard/auth-sessions/${encodeURIComponent(state.sessionID)}/claim?start_token=${encodeURIComponent(state.startToken)}`, { method: 'POST' });

package/dist/src/state/config.js

@@ -15,8 +15,8 @@ import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const DEV_BASE_URL = "https://dev.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.1.34";
-export const API_CONTRACT_REVISION = "sha256:80d69dbad36debbe4bdfbe468127a934c87b657e7795f369bb04de54863da476";
+export const CLI_VERSION = "2.1.40";
+export const API_CONTRACT_REVISION = "sha256:700d9834de969f16d0fc58cbbdbaa092f969f497e30e4ec291c790cea3e7f73a";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/docs/agent/buyer/cart-checkout.json

@@ -60,5 +60,6 @@
     "service execution",
     "resume",
     "contact"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

package/docs/agent/buyer/catalog-list.json

@@ -18,15 +18,16 @@
   ],
   "output_interpretation": {
     "item_format": "Explain the title, what the human receives, any auxiliary discovery step, and the published price.",
-    "service_flow": "Explain discovery as an auxiliary identity-confirmation step, including free quota and paid continuation. Present primary_service as the actual paid outcome. Read all values from the manifest.",
+    "service_flow": "Legacy catalog only: read service_flow facts as published; do not reinterpret old discovery/paid identities as a new public definition. New definitions expose operations within one service.",
     "variant_selection": "Internal IDs are for the Agent's next command only and are never shown or requested from the human.",
     "price_note": "amount_minor is in minor units (e.g., 10000 = 100.00 CNY). The CLI formats prices as XX.YY currency automatically.",
-    "railway": "Railway entries point to itpay docs show rail-booking; use its query and booking contracts instead of a generic start→invoke→cart sequence."
+    "railway": "Railway entries point to itpay docs show rail-booking; use its query and booking contracts instead of a generic start→invoke→cart sequence.",
+    "service_definition": "Prefer immutable service_definition: one public service with declared operations, pinned schemas and billing modes. Free query does not mean free purchase; dynamic needs a real quote. Do not choose a zero placeholder variant."
   },
   "agent_rules": [
     "Use catalog list only when the human asks for a new service, not when they want an earlier purchase.",
     "Read the variant IDs and prices from the output; do not invent them.",
-    "Explain the customer journey from service_flow instead of presenting every variant as an unrelated service.",
+    "Explain the returned public service operations and pricing; use legacy service_flow only when no service_definition is present.",
     "State free quota, paid continuation price, email requirement, and claim purpose exactly as published; do not exaggerate or omit conditions.",
     "Ask the human to choose only when multiple services could satisfy the goal; never make them choose an internal variant or offer ID.",
     "Use each service’s returned input contract; railway planning and booking follow rail-booking, not a universal Cart route."
@@ -68,5 +69,6 @@
     "what to buy",
     "有哪些",
     "服务列表"
-  ]
+  ],
+  "purchase_consent": "Candidate selection is not price approval. Service-backed quote/cart/checkout requires a current scoped approve_purchase record; use the complete server template, default false. Only genuine matching approval allows true; material price/subject/terms changes invalidate it. Restore an existing Checkout before creating anything."
 }

package/docs/agent/buyer/identity-and-sessions.json

@@ -92,12 +92,13 @@
     "chat"
   ],
   "auth_session_states": {
-    "stages": "The CLI now reports the auth session stage exactly as the server returns it: waiting_provider (show the handoff and wait), email_verification_required (the human must verify the emailed code on the auth page), merge_confirmation_required (an existing account matches — the human must confirm the merge on the auth page), provider_pending/pending (generic wait), completed (session done — bind it, do not restart).",
+    "stages": "Report the actual server stage: waiting_provider (show the official handoff), email_verification_required (explicit or legacy identity verification; follow the current official page), merge_confirmation_required (the human must prove both accounts and explicitly confirm or cancel the frozen merge), provider_pending/pending (wait), completed (bind the original session and resume the same service). Ordinary login needs one verified supported identity; do not require both phone and email.",
     "terminal_states": "auth_expired/auth_denied/auth_cancelled/auth_failed mean this session is over; say so plainly and respect denial or cancellation. Start a new session only on an explicit login request; never keep polling a dead one.",
     "transport_unknown": "auth_status_unknown means a network error while polling — the outcome is unknown. Keep waiting on the SAME session (it may still complete); do NOT restart auth, and do not assume denial.",
     "missing": "auth_session_missing means the cached session is gone. An explicit auth login opens one fresh official session in that call; auth status stays read-only.",
     "completed_resume": "After login completes, execute the returned command to resume the same paused service execution. Login does not silently run that command.",
-    "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first."
+    "path_b": "A buyer who reaches checkout without a login completes identity inside the protected checkout page; never force a separate itpay auth login first.",
+    "identity_binding": "Phone is recommended first, wallets next, email is a separate Other options choice. Extra identities are optional bindings. A phone conflict does not prove account ownership: independent target authentication and explicit human merge confirmation are required. Never use the same SMS proof twice, approve a merge for the user, or treat login/identity binding as payment consent. Service-specific contact requirements stay in the service."
   },
   "key_reset_decision": "Only after explicit user/operator acceptance of abandoning the old identity, consult device reset-key help; this is not automatic error recovery, and old execution access does not migrate."
 }