@itpay/cli 2.0.11 → 2.0.12

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/guidance.js

@@ -404,7 +404,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.",
             });
         }
@@ -487,6 +487,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 +507,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/services.js

@@ -128,7 +128,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} 后执行；否则停止`,
@@ -198,17 +198,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 +239,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 +302,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: [{
@@ -692,19 +706,26 @@ function servicesNextEnvelope(model) {
     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 +745,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/main.js

@@ -96,6 +96,10 @@ function reportCLIError(error, contract) {
         error.code === "platform_release_unavailable" ||
         (error.status === 404 && error.code === "unknown_error"));
     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 capabilityInputInvalid = error instanceof HttpError && error.code === "capability_input_invalid";
     const deviceRecovery = deviceError ? [{
             command: "itpay skill show itpay-buyer --json",
             reason: "读取身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
@@ -124,9 +128,17 @@ function reportCLIError(error, contract) {
                 ? "立即向用户报告 error.message 并结束本次任务。不要运行任何其他 itpay、npm、which、device、docs、cart、orders 或 services 命令；不要寻找、安装或切换其他 CLI。只有运营明确提供兼容 CLI 后，才能在新的任务中重新开始。"
                 : 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 并停止，不要自动重试。请求是否可能计费以 Backend 的消费事实为准；只有用户明确要求再次查询后，才可按 next/recovery 重新开始。"
+                            : providerRejected
+                                ? "上游拒绝了本次输入；向用户逐字报告 error.message 并停止，不要重试同一 Execution。Provider 已收到响应，本次请求可能计费；只有用户提供修正后的输入后，才可按 next/recovery 继续。"
+                                : 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 || backendInternal || providerConnectionUnavailable || providerTemporary || 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.12";
+export const API_CONTRACT_REVISION = "sha256:ea7d716f444a01e9d0109f12a53b56ce16d5ab813795a18a7a63f24a8c752073";
 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,7 @@
   ],
   "agent_rules": [
     "Install with npm install -g @itpay/cli.",
-    "Use the default https://dev.itpay.ai beta API unless an environment override is deliberate.",
+    "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；付款时把返回的二维码和链接实际展示到当前对话。",

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

@@ -62,6 +62,25 @@ 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"
+  },
+  "instruction": "Provider 请求未发出，预留免费额度已释放；当前 Execution 已失败。立即向用户报告 error.message 并停止，不要自动重试、不要继续同一 Execution，也不要进入任何付费路径。只有运营确认连接恢复且用户明确要求重新查询后，才启动新的 Service Execution。",
+  "next": null,
+  "recovery": []
+}
+```
+
+该终态不允许 CLI 猜测网络修复、重复 invoke 或转入购买。连接恢复后也不能复用失败 Execution；必须同时满足“运营已确认恢复”和“用户明确要求再次查询”，才创建新 Execution。
+
 ## 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/package.json

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

package/skills/itpay-buyer/SKILL.md

@@ -70,6 +70,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 +89,8 @@ 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.
+
 ## Safety
 
 - Never invent service, capability, item, Checkout, Order, grant, or refund IDs.