@itpay/cli 2.0.11 → 2.0.13

package/README.md

@@ -11,7 +11,7 @@ itpay --agent-type codex-desktop readyz --json
 # follow next.command: typed skill show, then catalog list
 ```
 
-The default API is temporarily `https://dev.itpay.ai` during the 2.0.11 beta. Set `ITPAY_BACKEND_URL` only for an intentional override.
+The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional environment override.
 
 ## Output Contract
 

package/dist/src/commands/compatibility.js

@@ -10,6 +10,11 @@ export async function requirePlatformCompatibility(backend) {
     throw new HttpError(426, {
         code: "client_upgrade_required",
         message: `CLI ${CLI_VERSION} contract ${API_CONTRACT_REVISION} is incompatible with platform ${platform.platform_revision} contract ${platform.api_contract_revision} (minimum CLI ${platform.minimum_cli_version}, maximum major ${platform.maximum_cli_major})`,
+        minimum_cli_version: platform.minimum_cli_version,
+        maximum_cli_major: platform.maximum_cli_major,
+        platform_revision: platform.platform_revision,
+        api_contract_revision: platform.api_contract_revision,
+        upgrade_command: `npm install -g @itpay/cli@${platform.minimum_cli_version}`,
     }, "CLI is incompatible with the active ItPay platform release");
 }
 function compareVersions(left, right) {

package/dist/src/commands/guidance.js

@@ -25,7 +25,7 @@ export function writeCommandEnvelope(value, options = {}) {
         return;
     }
     out(`${qualified.status}\n`);
-    const facts = "result" in qualified ? qualified.result : qualified.error;
+    const facts = "error" in qualified ? qualified.error : qualified.result;
     if (options.plainResult) {
         for (const line of options.plainResult)
             out(`${line}\n`);
@@ -34,6 +34,11 @@ export function writeCommandEnvelope(value, options = {}) {
         for (const [key, fact] of Object.entries(facts)) {
             out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
+        if ("error" in qualified && qualified.result) {
+            for (const [key, fact] of Object.entries(qualified.result)) {
+                out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+            }
+        }
     }
     if ("handoff" in qualified && qualified.handoff) {
         for (const [key, fact] of Object.entries(qualified.handoff)) {
@@ -404,7 +409,7 @@ function buildServiceGuidance(input) {
                 command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID}${emailRequired ? " --email <email>" : ""} --json`,
                 requires_human: true,
                 reason: emailRequired
-                    ? "Ask the human for their email. It is used to send the protected result claim link; never invent or substitute an address."
+                    ? deliveryEmailGuidance(checkoutCapability?.delivery_email_purpose)
                     : "This capability returns an agent-visible result after payment and does not require a delivery email.",
             });
         }
@@ -417,13 +422,7 @@ function buildServiceGuidance(input) {
         }
     }
     else if ((input.providerCalled || execution.next_action === "select_candidate") && (input.resultItems?.length ?? 0) === 0) {
-        nextActions.push({
-            id: "start_refined_search",
-            label: "Start a new execution with a more specific company name",
-            command: `itpay services start ${execution.service_id}`,
-            requires_human: true,
-            reason: "No candidates were found. This execution is finished; use one new execution per new keyword.",
-        });
+        // Terminal empty result: a later explicit human request starts a new flow.
     }
     else if (needsHumanSelection(execution, resultItem)) {
         nextActions.push({
@@ -433,12 +432,6 @@ function buildServiceGuidance(input) {
             requires_human: true,
             reason: "Do not choose a candidate without explicit human confirmation.",
         });
-        nextActions.push({
-            id: "start_another_search",
-            label: "Search another company in a new execution",
-            command: `itpay services start ${execution.service_id}`,
-            reason: "This execution has completed its one keyword lookup; do not reuse it for another keyword.",
-        });
     }
     else if (prePurchase) {
         const action = {
@@ -487,6 +480,7 @@ function buildServiceGuidance(input) {
                 requires_payment: capability.requires_payment,
                 vault_required: capability.vault_required,
                 delivery_email_required: capability.delivery_email_required,
+                delivery_email_purpose: capability.delivery_email_purpose,
                 price_amount_minor: capability.price_amount_minor,
                 price_currency: capability.price_currency,
                 free_quota_limit: capability.free_quota_limit,
@@ -506,6 +500,18 @@ function buildServiceGuidance(input) {
             : {}),
     };
 }
+function deliveryEmailGuidance(purpose) {
+    switch (purpose) {
+        case "receipt":
+            return "Ask the human for their email. It is used to send the order receipt; never invent or substitute an address.";
+        case "claim":
+            return "Ask the human for their email. It is used to send the protected result claim link; never invent or substitute an address.";
+        case "receipt_and_claim":
+            return "Ask the human for their email. It is used to send the order receipt and protected result claim link; never invent or substitute an address.";
+        default:
+            return "Ask the human for the required email and state only the Backend-declared purpose; never invent or substitute an address.";
+    }
+}
 function firstPrePurchaseCapability(capabilities) {
     return capabilities.find((capability) => capability.agent_visible && !capability.requires_payment)
         ?? capabilities.find((capability) => capability.agent_visible);

package/dist/src/commands/install.js

@@ -13,7 +13,7 @@ const INSTRUCTIONS = {
     "codex-cli": "在 Codex CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
-    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type；Checkout 返回 qr_image_url 时，必须按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
+    workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回 qr_image_url 时，按当次 instruction 调用 present_files 在右侧打开二维码，不要检查本地二维码文件。",
 };
 export function runInstall(target, options = {}) {
     if (!target || target === "list") {

package/dist/src/commands/services.js

@@ -106,13 +106,14 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
     const baseResult = {
         service_execution_id: response.execution.service_execution_id,
         capability_id: requestedCapability.capability_id,
+        query: input,
         items,
         ...(quota ? { quota } : {}),
     };
     let status = items.length > 0 ? "result_ready" : "no_result";
     let instruction = items.length > 0
         ? "向用户展示编号和 safe_payload；若候选列表已满足用户目标，在此停止。仅在用户明确选择并希望继续时，才在当前 Execution 提交对应 rank。"
-        : "Provider 已返回空结果；不要重放当前 execution，按下一步恢复。";
+        : `没有找到与“${queryText(input)}”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。`;
     let next = null;
     if (response.effective_quota?.exhausted) {
         status = "quota_exhausted";
@@ -128,7 +129,7 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
                 delivery_email_required: checkoutCapability.delivery_email_required,
             };
             const price = capabilityPrice(checkoutCapability);
-            instruction = purchaseConfirmationInstruction("quota_exhausted", price, checkoutCapability.delivery_email_required);
+            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} 后执行；否则停止`,
@@ -148,9 +149,7 @@ function invokedEnvelope(response, requestedCapability, capabilities, input) {
         };
     }
     else if (items.length === 0) {
-        next = response.provider_called
-            ? { command: `itpay services start ${response.execution.service_id}`, reason: "为新的服务输入启动新 execution" }
-            : { command: `itpay services next ${response.execution.service_execution_id} --json`, reason: "读取服务端恢复动作" };
+        next = null;
     }
     return {
         value: { status, result: baseResult, instruction, next, recovery: [] },
@@ -162,11 +161,18 @@ function serviceResultPlainLines(result) {
         `service_execution_id: ${String(result.service_execution_id)}`,
         `capability_id: ${String(result.capability_id)}`,
     ];
+    const items = result.items;
+    const query = result.query;
+    if (query) {
+        for (const [key, value] of Object.entries(query))
+            lines.push(`${key}: ${String(value)}`);
+    }
+    if (items.length === 0)
+        lines.push("results: 0");
     if (result.quota)
         lines.push(`quota: ${JSON.stringify(result.quota)}`);
     if (result.checkout)
         lines.push(`checkout: ${JSON.stringify(result.checkout)}`);
-    const items = result.items;
     if (items.length > 0) {
         lines.push("items:");
         for (const item of items) {
@@ -178,6 +184,10 @@ function serviceResultPlainLines(result) {
     }
     return lines;
 }
+function queryText(input) {
+    const value = Object.values(input).find((item) => typeof item === "string" && item.trim() !== "");
+    return typeof value === "string" ? value : JSON.stringify(input);
+}
 function missingRequiredInput(schema, input) {
     return requiredInputFields(schema).filter((field) => {
         if (!(field in input) || input[field] === null || input[field] === undefined)
@@ -198,17 +208,30 @@ function capabilityPrice(capability) {
         ? formatMoney(capability.price_amount_minor, capability.price_currency)
         : "当前发布价格";
 }
-function purchaseConfirmationInstruction(context, price, deliveryEmailRequired, candidateTitle = "") {
+function purchaseConfirmationInstruction(context, price, deliveryEmailRequired, deliveryEmailPurpose, candidateTitle = "") {
+    const emailPurpose = deliveryEmailPurposeText(deliveryEmailPurpose);
     if (context === "quota_exhausted") {
         return deliveryEmailRequired
-            ? `免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：继续当前请求需要支付 ${price}，交付还需要用户邮箱；请确认是否购买并提供邮箱。然后停止并等待。用户明确同意并提供真实邮箱前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。`
+            ? `免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：继续当前请求需要支付 ${price}，并提供${emailPurpose}；请确认是否购买并提供邮箱。然后停止并等待。用户明确同意并提供真实邮箱前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。`
             : `免费额度已用完，本次没有调用 Provider，也尚未创建 Quote 或 Checkout。现在只向用户说明：“继续当前请求需要支付 ${price}，是否购买？”然后停止并等待用户明确回复。用户明确同意前，不要执行 next.command，不要新建 Execution，不要尝试其他 capability、quote、cart、buy、checkout 或 pay 命令。`;
     }
     const selected = candidateTitle ? `已选择 ${candidateTitle}。` : "当前候选已经确认。";
     return deliveryEmailRequired
-        ? `${selected}候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明：继续购买后续服务需要支付 ${price}，并提供用于发送交付认领链接的邮箱；请确认是否购买并提供邮箱。然后停止。用户明确同意并提供真实邮箱前，不要执行 next.command，不要创建新 Execution 或 Checkout。`
+        ? `${selected}候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明：继续购买后续服务需要支付 ${price}，并提供${emailPurpose}；请确认是否购买并提供邮箱。然后停止。用户明确同意并提供真实邮箱前，不要执行 next.command，不要创建新 Execution 或 Checkout。`
         : `${selected}候选已绑定到当前 Execution，但尚未购买后续服务。现在只向用户说明：“继续购买后续服务需要支付 ${price}，是否购买？”然后停止。用户明确同意前，不要执行 next.command，不要创建新 Execution 或 Checkout。`;
 }
+function deliveryEmailPurposeText(purpose) {
+    switch (purpose) {
+        case "receipt":
+            return "用于发送订单收据的真实邮箱";
+        case "claim":
+            return "用于发送交付认领链接的真实邮箱";
+        case "receipt_and_claim":
+            return "用于发送订单收据和交付认领链接的真实邮箱";
+        default:
+            return "服务端声明用途的真实邮箱";
+    }
+}
 function paidContinuation(model, action, input) {
     if (!action.capability_id)
         return null;
@@ -226,6 +249,7 @@ function paidContinuation(model, action, input) {
                 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),
@@ -288,7 +312,7 @@ export async function runServicesAction(backend, serviceExecutionID, actionType,
                 ...(continuation ? { checkout: continuation.checkout } : {}),
             },
             instruction: continuation
-                ? purchaseConfirmationInstruction("candidate_selected", continuation.price, continuation.capability.delivery_email_required, selection.title)
+                ? purchaseConfirmationInstruction("candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose, selection.title)
                 : "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
             next,
             recovery: [{
@@ -681,30 +705,37 @@ function servicesNextEnvelope(model) {
                 ? selection
                     ? "Agent-visible 搜索已完成。向用户展示 items 中的编号、title 和 safe_payload，然后停止；不要调用 read-result。只有用户明确选择候选并要求继续时，才执行 next.command。"
                     : "这是当前 Graph 步骤对应的交付；结果已可供 Agent 使用，只使用 safe_payload。"
-                : "Agent-visible 交付已完成但没有结果项；不要调用 read-result 或重放当前 execution。",
+                : "Agent-visible 交付已完成但有 0 个结果。向用户展示空结果并停止；不要调用 read-result、重放当前 Execution、修改输入或创建新 Execution。",
             next: selection ? {
                 command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank> --json`,
                 reason: "仅在用户明确选择后锁定来源候选",
             } : null,
-            recovery: items.length > 0 ? [] : [{ command: `itpay services get ${execution.service_execution_id} --json`, reason: "检查交付时间线" }],
+            recovery: [],
         };
     }
     if (deliveryMode === "vault_artifact") {
         const grantStatus = normalizeGrantStatus(delivery?.grant_status);
         const grantActive = grantStatus === "active";
+        const grantPending = grantStatus === "pending";
         return {
-            status: grantActive ? "grant_active" : "human_authorization_required",
+            status: grantActive ? "grant_active" : grantPending ? "result_preparing" : "human_authorization_required",
             result: {
                 service_execution_id: execution.service_execution_id,
                 ...(delivery?.capability_id ? { capability_id: delivery.capability_id } : {}),
                 delivery_mode: deliveryMode,
                 grant_status: grantStatus,
+                ...(delivery?.preparation ? { preparation: delivery.preparation } : {}),
                 ...(grantActive && delivery?.grant_expires_at ? { grant_expires_at: delivery.grant_expires_at } : {}),
             },
             instruction: grantActive
                 ? "这是当前 Graph 步骤对应的交付；用户授权有效，立即读取并遵守字段范围与到期时间。"
-                : "这是当前 Graph 步骤对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
-            next: {
+                : grantPending
+                    ? "用户已经完成授权，服务端正在按已发布执行图准备交付内容。不要再次付款、再次授权、新建 Execution 或调用 read-result；只执行 next.command 查询同一 Execution。"
+                    : "这是当前 Graph 步骤对应的交付；请用户在订单页面授权，未授权前不要读取或猜测内容。",
+            next: grantPending ? {
+                command: `itpay services next ${execution.service_execution_id} --json`,
+                reason: "等待同一 Execution 的交付准备完成",
+            } : {
                 command: `itpay services read-result ${execution.service_execution_id} --json`,
                 reason: grantActive ? "读取当前有效 grant 的结果" : "仅在用户确认授权后执行",
             },
@@ -724,7 +755,7 @@ function servicesNextEnvelope(model) {
                     phase: execution.phase,
                     checkout: continuation.checkout,
                 },
-                instruction: purchaseConfirmationInstruction(execution.status === "quota_exhausted" ? "quota_exhausted" : "candidate_selected", continuation.price, continuation.capability.delivery_email_required),
+                instruction: purchaseConfirmationInstruction(execution.status === "quota_exhausted" ? "quota_exhausted" : "candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose),
                 next: continuation.next,
                 recovery: [],
             };

package/dist/src/commands/skill.js

@@ -24,7 +24,7 @@ export function runSkillShow(name, options = {}) {
         result: { skill: BUYER_SKILL, content },
         instruction: agentType
             ? agentType === "workbuddy"
-                ? "完整读取并遵守 Skill；保持 workbuddy、同一 Node/CLI launcher 和可持久写入 Device 状态的执行权限。内部诊断不要逐步转述给用户。"
+                ? "完整读取并遵守 Skill；保持 workbuddy 和同一 Node/CLI launcher。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。"
                 : `完整读取并遵守 Skill；当前 Agent Type 是 ${agentType}，后续命令保持不变。`
             : "完整读取并遵守 Skill；先如实选择当前运行环境对应的 Agent Type。",
         next: agentType

package/dist/src/main.js

@@ -95,7 +95,16 @@ function reportCLIError(error, contract) {
         error.code === "client_compatibility_headers_required" ||
         error.code === "platform_release_unavailable" ||
         (error.status === 404 && error.code === "unknown_error"));
+    const requiredCLIVersion = incompatible && error instanceof HttpError && /^\d+\.\d+\.\d+$/.test(error.payload?.minimum_cli_version ?? "")
+        ? error.payload.minimum_cli_version
+        : undefined;
     const backendInternal = error instanceof HttpError && error.status === 500 && error.code === "internal_error";
+    const providerConnectionUnavailable = error instanceof HttpError && error.code === "provider_connection_unavailable";
+    const providerTemporary = error instanceof HttpError && error.code === "provider_temporarily_unavailable";
+    const providerRejected = error instanceof HttpError && error.code === "provider_rejected";
+    const providerInputRejected = error instanceof HttpError && error.code === "provider_input_rejected";
+    const providerContractMismatch = error instanceof HttpError && error.code === "provider_contract_mismatch";
+    const capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceRecovery = deviceError ? [{
             command: "itpay skill show itpay-buyer --json",
             reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
@@ -120,13 +129,50 @@ function reportCLIError(error, contract) {
                 code: incompatible ? "backend_contract_incompatible" : commandError?.code ?? (error instanceof HttpError ? error.code : stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
+            ...(requiredCLIVersion ? {
+                result: {
+                    current_cli_version: CLI_VERSION,
+                    required_cli_version: requiredCLIVersion,
+                },
+            } : error instanceof HttpError && error.payload?.service_execution_id ? {
+                result: {
+                    service_execution_id: error.payload.service_execution_id,
+                    provider_called: error.payload.provider_called === true,
+                    ...(error.payload.effective_quota ? {
+                        quota: {
+                            remaining: error.payload.effective_quota.remaining,
+                            limit: error.payload.effective_quota.limit,
+                        },
+                    } : {}),
+                },
+            } : {}),
             instruction: incompatible
-                ? "立即向用户报告 error.message 并结束本次任务。不要运行任何其他 itpay、npm、which、device、docs、cart、orders 或 services 命令；不要寻找、安装或切换其他 CLI。只有运营明确提供兼容 CLI 后，才能在新的任务中重新开始。"
+                ? requiredCLIVersion
+                    ? "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。"
+                    : "立即向用户报告 error.message 并结束本次任务。Backend 未提供可验证的兼容 CLI 版本；不要运行其他 ItPay 或 npm 命令，不要猜测版本、切换 Agent Type 或删除 Device 身份。"
                 : backendInternal
                     ? "Backend 内部故障；立即停止并向用户报告。不要重试、检查或删除 Device 身份、创建替代 Execution、切换 Backend，或尝试 quote、checkout、cart、buy、pay 等付费路径。"
-                    : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
+                    : providerConnectionUnavailable
+                        ? "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。"
+                        : providerTemporary
+                            ? "上游服务暂时不可用；向用户逐字报告 error.message 和 result.quota 并停止，不要自动重试、不要创建新 Execution。只有用户之后明确提出新请求，才可重新开始。"
+                            : providerInputRejected
+                                ? `Provider 明确拒绝了该输入：${error instanceof Error ? error.message : String(error)}。请向用户报告 error.message 和 result.quota 并停止。不要自行修改输入、不要重试、不要创建新 Execution；只有用户明确提供新输入后才能重新查询。`
+                                : providerContractMismatch
+                                    ? "Provider 响应与已发布契约不一致。这不是用户输入问题。立即停止，不要修改输入、不要重试、不要创建新 Execution，也不要进入付费路径；向用户报告平台故障和 result.quota。"
+                                    : providerRejected
+                                        ? "Provider 拒绝了本次请求，但未声明这是输入错误；向用户逐字报告 error.message 和 result.quota 并停止。不要修改输入、不要重试、不要创建新 Execution。"
+                                        : capabilityInputInvalid
+                                            ? "输入未通过本地校验，上游尚未被调用且用户额度未变化。向用户逐字报告 error.message 并停止，不要原样重试或运行其他恢复命令。用户提供修正后的输入后，继续使用当前未结束的 Execution。"
+                                            : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
-            recovery: incompatible || backendInternal ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+            recovery: incompatible
+                ? requiredCLIVersion
+                    ? [{ command: `npm install -g @itpay/cli@${requiredCLIVersion}`, reason: "安装 Backend 指定的兼容 CLI 版本" }]
+                    : []
+                : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
+                    ? []
+                    : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
             ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : {}),
             output: (text) => { process.stderr.write(text); },

package/dist/src/state/config.js

@@ -9,9 +9,9 @@ import { BackendClient } from "../client/backend.js";
 import { declaredAgentType } from "./agent_type.js";
 import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
-export const DEFAULT_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.11";
-export const API_CONTRACT_REVISION = "sha256:3779f5468ea2109d4134c4ace66258c9eabe82461fa86e83c84df8c860276886";
+export const DEFAULT_BASE_URL = "https://app.itpay.ai";
+export const CLI_VERSION = "2.0.13";
+export const API_CONTRACT_REVISION = "sha256:7f4c40b082292bf823631bcd37d452f4a8537153e30636d5eb3a2b24a77ce602";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/docs/agent/buyer/install-and-setup.json

@@ -32,7 +32,9 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
-    "Use the default https://dev.itpay.ai beta API unless an environment override is deliberate.",
+    "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and run only the exact npm install recovery returned by the CLI; never replace its version with latest.",
+    "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
+    "Use the default https://app.itpay.ai API unless an environment override is deliberate.",
     "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, or workbuddy.",
     "One local private key is reused, but each exact Backend API base URL has its own server registration and quota lineage.",
     "Within one Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",

package/docs/cli-reference/commands/install.md

@@ -29,7 +29,7 @@ itpay install [target] [--json]
   "result": {
     "agent_type": "codex-desktop",
     "default_host": "codex",
-    "default_api": "https://dev.itpay.ai",
+    "default_api": "https://app.itpay.ai",
     "install_command": "npm install -g @itpay/cli"
   },
   "instruction": "在 Codex Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
@@ -83,7 +83,7 @@ itpay install [target] [--json]
 | `codex-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
 | `claude-code-desktop` | `claude-code` | 桌面对话必须实际展示二维码和付款链接。 |
 | `claude-code-cli` | `terminal` | 只在用户可见终端展示付款交接。 |
-| `workbuddy` | `plain-chat` | Checkout 返回 `qr_image_url` 时，按当次 instruction 调用 `present_files` 在右侧打开二维码；不检查本地二维码文件。 |
+| `workbuddy` | `plain-chat` | 会持久化 `~/.itpay-v3` 的 Bash 调用先设 Shell 工具参数 `dangerouslyDisableSandbox=true`；拒绝权限时停止，不切换 Node、不删除 identity、不处理 lock。Checkout 返回 `qr_image_url` 时按 instruction 调用 `present_files`。 |
 
 显式 `--host` 可以在后续 commerce 命令覆盖默认 Host，但不会改变 Agent Type 或设备归属。
 

package/docs/cli-reference/commands/readyz.md

@@ -33,6 +33,32 @@ itpay readyz [--json]
 
 连接失败时返回 `backend_unavailable`，要求核对 `ITPAY_BACKEND_URL` 后重试同一命令，不得继续下单。
 
+CLI 已取得 Backend 的兼容性合同、但当前版本或 contract hash 不匹配时，返回一个可执行且版本固定的恢复动作：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "backend_contract_incompatible",
+    "message": "CLI 2.0.13 contract sha256:client is incompatible with platform v3.example contract sha256:server (minimum CLI 2.0.14, maximum major 2)"
+  },
+  "result": {
+    "current_cli_version": "2.0.13",
+    "required_cli_version": "2.0.14"
+  },
+  "instruction": "当前 CLI 与 Backend 合约不兼容。停止所有 ItPay 业务命令；只执行 recovery.command，将 @itpay/cli 更新到 Backend 指定的精确版本。安装完成后确认 itpay --version 与 result.required_cli_version 完全一致，再重新运行 readyz。不要安装 latest、猜测版本、切换 Agent Type 或删除 Device 身份。",
+  "next": null,
+  "recovery": [
+    {
+      "command": "npm install -g @itpay/cli@2.0.14",
+      "reason": "安装 Backend 指定的兼容 CLI 版本"
+    }
+  ]
+}
+```
+
+只允许使用 Backend 返回的 `minimum_cli_version` 生成精确 npm 版本。兼容性合同不可用、缺少合法版本或仅有无法验证的错误文本时，仍须停止且不得猜测安装版本。
+
 ## Agent Type / Host
 
 本命令不渲染 Host 内容。若已声明 Agent Type，`result.agent_type` 会确认该类型，且返回的 Skill 命令保留同一 `--agent-type`；未声明时 Skill 会先引导 `install`。

package/docs/cli-reference/commands/services/invoke.md

@@ -5,7 +5,7 @@
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。
 
 **上游：** `services start/next` 明确返回 invoke。
-**下游：** 候选结果、人工 action、付费 Quote 或新 execution。
+**下游：** 候选结果、人工 action 或付费 Quote。一次 invoke 没有结果或返回 Provider 错误时必须停止；只有用户之后明确提供新输入，才启动新的 execution。
 
 ## 语法与参数
 
@@ -33,9 +33,31 @@ itpay services invoke <service_execution_id> --capability <capability_id>
 }
 ```
 
-## 无结果与额度耗尽
+## 无结果
 
-无结果时明确说明 Provider 已返回空结果，并根据服务端 graph 决定重试同一 execution 或启动新 execution。额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
+Provider 已收到请求但没有匹配项时，该 invocation 成功完成、提交一次真实额度消费并返回权威剩余额度。CLI 不提供可自动执行的下一步：Agent 必须展示 0 个结果并停止，不得缩短、改写或猜测输入。
+
+```json
+{
+  "status": "no_result",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "company_name_suggestion",
+    "query": { "keyword": "北京赢在未来公司" },
+    "items": [],
+    "quota": { "remaining": 1, "limit": 3 }
+  },
+  "instruction": "没有找到与“北京赢在未来公司”匹配的结果。向用户展示本次为 0 个结果并停止。不要修改、缩短或猜测其他输入；只有用户明确提供新输入后，才能启动新的查询。",
+  "next": null,
+  "recovery": []
+}
+```
+
+文本输出只包含 execution、capability、keyword、`results: 0`、quota 和同一条 instruction；不得附带 Provider raw payload、Operation ID 或调试信息。
+
+## 额度耗尽
+
+额度耗尽时，普通单 Execution 流程返回完整的 `services checkout` 单项快捷命令；`services quote -> cart add --quote -> buy --cart` 只用于用户明确要求把多个独立 Execution 合并付款的高级流程。
 
 ```json
 {
@@ -62,6 +84,70 @@ itpay services invoke <service_execution_id> --capability <capability_id>
 
 缺少 required input 时返回 `capability_input_invalid`，recovery 给出带占位符的同一 invoke 命令；CLI 和 Backend 都必须在 Provider 调用前拒绝，Backend 还必须在 execution/event/quota/invocation 写入前拒绝。错误调用付费 capability 时不得给出购买旁路，只能回到同一 Execution 的 `services next`；execution 状态、event、ProviderCalled 均保持不变。
 
+## Provider 请求前连接失败
+
+如果 Backend 能确认请求未发出，返回固定的终态错误，不暴露 DNS、IP、Provider URL 或凭证诊断：
+
+```json
+{
+  "status": "error",
+  "error": {
+    "code": "provider_connection_unavailable",
+    "message": "provider request was not sent; reserved quota was released"
+  },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": false,
+    "quota": { "remaining": 3, "limit": 3 }
+  },
+  "instruction": "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。",
+  "next": null,
+  "recovery": []
+}
+```
+
+`result.quota` 是释放预留后的权威余额，不是请求前预留时的临时值。该终态不允许 CLI 猜测网络修复、重复 invoke 或转入购买。连接恢复后也不能复用失败 Execution；必须同时满足“运营已确认恢复”和“用户明确要求再次查询”，才创建新 Execution。
+
+## Provider 输入、临时和契约错误
+
+Provider 已收到请求时，Backend 返回同一 Execution 的权威调用和额度事实。CLI 不读取 raw payload，也不自行推断错误种类。
+
+明确输入错误：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "provider_input_rejected", "message": "输入的名称不合法" },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": true,
+    "quota": { "remaining": 0, "limit": 3 }
+  },
+  "instruction": "Provider 明确拒绝了该输入：输入的名称不合法。请向用户报告 error.message 和 result.quota 并停止。不要自行修改输入、不要重试、不要创建新 Execution；只有用户明确提供新输入后才能重新查询。",
+  "next": null,
+  "recovery": []
+}
+```
+
+契约错误：
+
+```json
+{
+  "status": "error",
+  "error": { "code": "provider_contract_mismatch", "message": "provider response did not match the published contract" },
+  "result": {
+    "service_execution_id": "<id>",
+    "provider_called": true,
+    "quota": { "remaining": 0, "limit": 3 }
+  },
+  "instruction": "Provider 响应与已发布契约不一致。这不是用户输入问题。立即停止，不要修改输入、不要重试、不要创建新 Execution，也不要进入付费路径；向用户报告平台故障和 result.quota。",
+  "next": null,
+  "recovery": []
+}
+```
+
+`provider_temporarily_unavailable` 同样必须停止且不得自动重试。输入错误、临时错误和契约错误都不得返回 `next.command` 或 recovery 命令；新的 Provider 请求只允许来自用户后续明确提出的新输入。
+
 ## Agent Type / Host
 
 `codex-desktop`、`codex-cli`、`claude-code-desktop`、`claude-code-cli`、`workbuddy` 五种 Agent Type 的 safe result 一致。instruction 可以适配对话表述，但不得隐藏 quota、价格或 schema 错误。

package/docs/cli-reference/commands/services/next.md

@@ -65,7 +65,7 @@ itpay services next <service_execution_id> [--json]
       }
     ]
   },
-  "instruction": "付费模糊搜索已完成。现在把 items 中的编号、title 和 safe_payload 展示给用户，然后停止。本结果是 agent-visible，不要调用 read-result。若用户的目标只是搜索候选企业，任务已经完成；只有用户之后明确选择某个候选并要求继续时，才执行 next.command。不要自动购买后续报告。",
+  "instruction": "付费 Agent-visible 搜索已完成。现在把 items 中的编号、title 和 safe_payload 展示给用户，然后停止。本结果是 agent-visible，不要调用 read-result。若用户的目标只是候选搜索，任务已经完成；只有用户之后明确选择某个候选并要求继续时，才执行 next.command。不要自动购买后续报告。",
   "next": {
     "command": "itpay services action <id> --action select_candidate --actor-type human --status approved --candidate <rank> --json",
     "reason": "仅在用户明确选择候选并要求继续时执行"
@@ -98,6 +98,33 @@ itpay services next <service_execution_id> [--json]
 }
 ```
 
+用户已经授权、但服务端仍在按已发布执行图准备 Vault 交付时，必须只轮询同一 Execution：
+
+```json
+{
+  "status": "result_preparing",
+  "result": {
+    "service_execution_id": "<id>",
+    "capability_id": "<capability_id>",
+    "delivery_mode": "vault_artifact",
+    "grant_status": "pending",
+    "preparation": {
+      "status": "running",
+      "total_nodes": 4,
+      "completed_nodes": 2,
+      "succeeded_nodes": 2,
+      "failed_nodes": 0
+    }
+  },
+  "instruction": "用户已经完成授权，服务端正在按已发布执行图准备交付内容。不要再次付款、再次授权、新建 Execution 或调用 read-result；只执行 next.command 查询同一 Execution。",
+  "next": {
+    "command": "itpay services next <id> --json",
+    "reason": "等待同一 Execution 的交付准备完成"
+  },
+  "recovery": []
+}
+```
+
 有效 grant 存在时：
 
 ```json

package/docs/cli-reference/commands/skill.md

@@ -14,4 +14,4 @@ itpay [--agent-type <agent_type>] skill show itpay-buyer [--json]
 
 Skill 是操作和安全合同，不是服务端业务状态。执行时仍以每个命令当前 envelope 的 `result`、`instruction` 和 `next` 为准。
 
-所有 Agent Type 使用相同的 JSON 外壳、字段和命令参数。`workbuddy` 只在 `instruction` 中额外强调保持同一 Node/CLI launcher、持久写权限和减少内部诊断转述；它不改变输入或输出 schema。
+所有 Agent Type 使用相同的 JSON 外壳、字段和命令参数。`workbuddy` 只在 `instruction` 中额外要求：写入 `~/.itpay-v3` 前把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`；权限被拒绝时停止，不切换 Node、不删除 identity、不处理 lock。它不改变输入或输出 schema。

package/docs/cli-reference/conventions.md

@@ -70,6 +70,9 @@ next: <one command>
 - 用户口头说“已付款”不是支付事实；仅服务端 `verified` 状态有效。
 - `agent_device_session_required` 只触发一次 session 续期和同请求重试；第二次失败必须返回，不得循环或换身份。
 - `device_state_unwritable` 表示当前运行环境不能可靠持久化 `~/.itpay-v3`；保持同一 Agent Type 与 CLI/Node launcher，恢复 Host 写权限后重试原命令，不得手工造 lock、删除身份或换运行时碰运气。
+- WorkBuddy 在运行会持久化 `~/.itpay-v3` 的 ItPay Bash 命令前，必须把 Shell 工具参数 `dangerouslyDisableSandbox` 设为 `true`。若用户拒绝该权限，命令尚未执行：停止并报告，不得切换 Node、删除 identity、手工处理 lock 或换 Agent Type。
+- `provider_input_rejected` 只表示 Provider 明确声明输入无效；`provider_contract_mismatch` 表示响应无法按已发布契约解释，绝不能归咎于用户输入。两者都必须停止且没有自动 recovery。
+- `backend_contract_incompatible` 只有在 Backend 返回合法 `minimum_cli_version` 时才能提供一个精确的 `npm install -g @itpay/cli@<version>` recovery。不得使用 `latest`、解析 message 猜版本或继续任何业务命令；升级后必须先用 `itpay --version` 核对完全一致，再重新运行 `readyz`。
 
 ## Instruction 模板
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.11",
+  "version": "2.0.13",
   "description": "ItPay CLI for V3 checkout, payment, order, refund, and agent-facing render flows.",
   "type": "module",
   "bin": {

package/skills/itpay-buyer/SKILL.md

@@ -13,6 +13,7 @@ Use the CLI as the only ItPay control surface. Never recreate API calls or hardc
 ## Envelope Rule
 
 - Keep one honest Agent Type, CLI/Node launcher, and Host permission context. Supported types: `codex-desktop`, `codex-cli`, `claude-code-desktop`, `claude-code-cli`, `workbuddy`.
+- WorkBuddy: before any ItPay Bash command that persists `~/.itpay-v3`, set the Shell tool parameter `dangerouslyDisableSandbox` to `true`. If the human denies that permission, the command did not run: stop and report it. Never switch Node, delete identity, edit locks, or change Agent Type.
 - Windows, tasks, chats, processes, and model sessions are not new Agents. Never rotate Agent Type or identity to reset quota.
 - Read `status` and `result` as facts, follow `instruction`, and execute at most the applicable `next.command`; use `recovery` only when it cannot continue.
 - `next.command` is not unconditional. If the result satisfies the user's goal, present useful facts and stop; never dump the whole envelope.
@@ -30,6 +31,8 @@ itpay --agent-type <agent_type> readyz --json
 
 Follow the returned `next.command`. After typed `readyz`, read this complete Skill again, then continue to Catalog.
 
+If `backend_contract_incompatible` returns `result.required_cli_version`, stop every ItPay business command. Run only its exact `npm install -g @itpay/cli@<version>` recovery; never substitute `latest`. Confirm `itpay --version` exactly matches the required version, then restart with typed `readyz`. Never change Agent Type or Device identity to bypass compatibility.
+
 ## Identity And Sessions
 
 - One local Ed25519 private key represents this installation. Never expose, copy, delete, or rotate it during normal recovery.
@@ -70,6 +73,7 @@ Run `next.command` only after the human says they acted or asks for status. QR r
 
 - Agent-visible results come from `services next`; do not use `read-result` for them.
 - Protected results require a current 15-minute human grant scoped to one delivery, approved fields, and frozen Agent audience.
+- If `services next` returns `result_preparing`, authorization is already complete. Run only its same-Execution `next.command`; do not pay, authorize, start, or call `read-result` again.
 - An Execution may have delivery history; follow `services next` for the Backend-selected current delivery.
 - A pending refund locks delivery and revokes active grants. Follow the returned refund command and state.
 
@@ -88,6 +92,10 @@ itpay --agent-type <agent_type> refund get <refund_request_id> --json
 
 Reuse the same Execution and Checkout. Never start another Execution, create another Checkout, change payment route, or replay a capability to bypass quota, selection, payment, delivery, grant, or refund state.
 
+`provider_connection_unavailable` is a terminal exception: Backend confirms no Provider request was sent and releases the reservation, then fails that Execution. Stop with no recovery command. Only after an operator confirms connectivity is restored and the human explicitly asks to query again may you start a new Execution.
+
+`no_result` is a completed Provider call with zero items. Show the query, zero results, and the returned quota, then stop. Never shorten, rewrite, or guess another input. `provider_input_rejected`, `provider_temporarily_unavailable`, and `provider_contract_mismatch` are also terminal for the current request: report the exact safe message and quota facts, run no recovery command, and wait for a new explicit human request.
+
 ## Safety
 
 - Never invent service, capability, item, Checkout, Order, grant, or refund IDs.