@itpay/cli 2.0.2 → 2.0.5

package/README.md

@@ -1,152 +1,102 @@
 # ItPay CLI
 
-The V3 terminal and agent-facing CLI for ItPay commerce.
+The official V3 CLI for Agent-driven ItPay service discovery, checkout, delivery, order recovery, and refunds.
 
 ```bash
 npm install -g @itpay/cli
-itpay readyz
-itpay docs show quickstart
+itpay install --json
+itpay --agent-type codex-desktop readyz --json
+itpay --agent-type codex-desktop catalog list --json
 ```
 
-The CLI defaults to the production API at `https://api.itpay.ai`. Set
-`ITPAY_BACKEND_URL` only when intentionally using another backend.
-
-## Commands
-
-- `itpay readyz` — `GET /v1/readyz`
-- `itpay next [--json]` — show the next recommended agent action from remembered server handles
-- `itpay cart add --item <id> --variant <id> --offer <id> [--quantity 1] [--input <json>] [--host <host>] [--json]` — create/update the canonical server cart; service-backed lines return `service_execution_id`
-- `itpay cart next [--json]` — show the next recommended action for the remembered canonical server cart
-- `itpay cart add --local ...` — explicit local draft compatibility mode only, not valid for service-backed flows
-- `itpay cart remove --line <cart_item_id>` — soft-remove an active line from the canonical server cart; quote-locked or checkout-bound lines are rejected
-- `itpay cart remove --local --variant <id> --offer <id>` — drop a local draft line
-- `itpay cart show` — print the canonical server cart, or local draft fallback when no server cart handle exists
-- `itpay cart clear` — abandon the canonical server cart and clear local handles
-- `itpay cart clear --local` — clear local handles/draft only
-- `itpay buy --cart <cart_id> --host <host> [--target <target>] [--qr-format ...] [--qr-file <path>]` — create checkout from a canonical server cart and render the branded checkout QR for the host
-- `itpay buy --host <host> [--target <target>] [--item ... --variant ... --offer ...] [--quantity 1]` — compatibility one-shot cart + checkout path
-- `itpay services start <service_id>` — start a generic Service Execution run
-- `itpay services invoke <service_execution_id> --capability <capability_id> --input key=value` — invoke an agent-visible capability
-- `itpay services action <service_execution_id> --action <action_type> [--result-item <id>]` — record a human/agent service action
-- `itpay services checkout <service_execution_id> --capability <capability_id> [--email <email>] [--host <host>] [--json]` — create quote lock from Service Execution state, require email only for capabilities that deliver a claim link, persist the handoff, and render the branded ItPay checkout
-- `itpay services checkout <service_execution_id> --resume --json` — reissue a lost or expired handoff for the same unpaid checkout without asking for contact information again
-- `itpay services next <service_execution_id> [--json]` — show the next recommended action from the Service Execution read model
-- `itpay services get <service_execution_id>` / `itpay services events <service_execution_id>` — read the redacted Service Execution timeline
-- `itpay checkout --id <checkout_id> --token <display_token>` — read canonical checkout presentation
-- `itpay pay --checkout <id> --method alipay|wechatpay` — CLI escape hatch for operator/manual testing only; normal buyer flow opens the ItPay checkout page first
-- `itpay order <order_id>` — read one V3 order
-- `itpay orders [--limit 20] [--status <status>]` — list account-scoped orders (requires `ITPAY_BEARER_TOKEN`)
-- `itpay refund --order <id> --payment-intent <id> --amount-minor <n> --currency <code>` — request a refund
-
-## Hosts
-
-The CLI dispatches to a per-host renderer based on `--host`:
-
-| `--host` | Renderer | Native UI |
-| --- | --- | --- |
-| `terminal` | `render/terminal.ts` | terminal QR + summary |
-| `codex`, `claude-code` | `render/markdown.ts` | markdown image + links |
-| `telegram` | `render/telegram.ts` | openclaw `message send` with inline buttons |
-| `feishu`, `lark` | `render/feishu.ts` | Feishu/Lark interactive card (url + callback) |
-| `discord`, `whatsapp`, `plain-chat` | `render/plain_chat.ts` | text + links, no native buttons |
-
-Aliases: `tg` and `openclaw-telegram` map to `telegram`; `feishu_im` and `fs` map to `feishu`.
+The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional test or local environment.
+
+## Output Contract
+
+Normal JSON commands return one bounded envelope:
+
+```text
+status      current command state
+result      facts needed at this step
+handoff     optional human-visible URL/image fields for the current Host
+instruction how the Agent must use the result
+next        zero or one preferred executable command
+recovery    exceptional recovery commands only
+```
+
+Run `next.command` unchanged after filling only explicit placeholders or user-provided required fields. Do not inspect raw APIs or hardcode a service workflow.
+
+Normative per-command contracts: [CLI Command Reference](docs/cli-reference/index.md).
+
+## Supported Agent Types
+
+| Agent Type | Default Host |
+| --- | --- |
+| `codex-desktop` | `codex` |
+| `codex-cli` | `terminal` |
+| `claude-code-desktop` | `claude-code` |
+| `claude-code-cli` | `terminal` |
+| `workbuddy` | `plain-chat` |
+
+`--agent-type` identifies the stable runtime and registered Agent instance. `--host` only selects the human presentation surface. Use `itpay install <agent_type> --json` for the exact responsibility.
+
+## Command Families
+
+- `readyz`, `catalog list`: compatibility and discovery.
+- `services start/invoke/action/checkout/next`: generic Service Execution flow.
+- `cart add/show/remove/clear/next`, `buy`: canonical Cart and ordinary Checkout flow.
+- `checkout`: authoritative payment and fulfillment recovery.
+- `services read-result`: read one human-granted protected result.
+- `order`, `orders`: exact order and account order views.
+- `refund create/list/get/watch/cancel`: Refund Owner flow.
+- `services get/events`: redacted support diagnostics; normal flows should use `services next`.
+- `install`, `docs list/show/search`: offline packaged guidance.
+- `pay`: operator escape hatch only; normal buyers use the ItPay Checkout page.
+
+Run `itpay <command> --help` or browse [the command index](docs/cli-reference/index.md) for parameters.
+
+## Recovery
+
+Use server-backed recovery before creating another resource:
+
+```bash
+itpay --agent-type <agent_type> next --json
+itpay --agent-type <agent_type> services list --json
+itpay --agent-type <agent_type> services next <service_execution_id> --json
+itpay --agent-type <agent_type> services checkout <service_execution_id> --resume --json
+itpay checkout --id <checkout_id> --token <display_token> --json
+```
+
+The local `~/.itpay-v3` directory stores the signed Device Authority, Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative.
 
 ## Environment
 
-- `ITPAY_BACKEND_URL` — optional backend override (default `https://api.itpay.ai`)
-- `ITPAY_BEARER_TOKEN` — account-scoped session token (only needed for `orders`)
-- `ITPAY_AGENT_DEVICE_ID` — agent device id, used for cart/service execution quota identity and `client_context`
-- `ITPAY_CURRENCY` — checkout currency (default `CNY`)
-- `ITPAY_IDEMPOTENCY_KEY` — `Idempotency-Key` for pay/refund requests (auto-generated if unset)
-- `ITPAY_IDE_IMAGE_ATTACH` — set to `0` to disable the IDE image-attach contract (e.g. read-only runner FS). Default `1`.
-- `ITPAY_IDE_IMAGE_DIR_OVERRIDE` — override the canonical IDE image directory instead of `$TMPDIR/itpay-v3-qr`. Useful when the IDE file panel only knows one path.
-
-## Agent next actions
-
-Service-backed flows return progressive guidance for agents:
-
-- `itpay cart add --json`, `itpay services start`, `itpay services invoke`,
-  `itpay services action`, `itpay services get`, and
-  `itpay services checkout --json` include top-level `next_actions`.
-- `itpay next`, `itpay cart next`, and `itpay services next <id>` print only
-  the next recommended command and recovery commands.
-- The guidance is derived from server cart and Service Execution read models.
-  Local `~/.itpay-v3/cart.json` only stores handles such as `cart_id`,
-  `service_execution_id`, `checkout_id`, and `display_token`.
-
-Agents should prefer `next_actions` over hardcoded service-specific flows.
-For example, a service-backed cart add can return an invoke command for an
-agent-visible free capability, while a quote-locked execution can return the
-checkout handoff command.
-
-## IDE image attach
-
-Every `itpay buy`, `itpay services checkout` (and `itpay checkout`,
-`itpay order`) downloads the
-brand checkout QR from the backend and writes it to a stable local
-file the agent can hand to the IDE image viewer (Trae `Read` tool,
-Codex, Claude Code). The contract is:
-
-- canonical file: `<os.tmpdir()>/itpay-v3-qr/itpay-v3-<kind>-<id>.png`
-  (override with `ITPAY_IDE_IMAGE_DIR_OVERRIDE`)
-- when `/tmp/itpay-v3-qr` is a separate, writable location it gets a
-  mirror of the same file under the same name
-- filename is stable per checkout, so re-runs overwrite the same
-  local file rather than scattering copies across the scratch dir
-
-Outputs that carry the IDE image attach:
-
-- `itpay buy --json` — fields `brand_qr_local_path`, `brand_qr_mirrors`,
-  `brand_qr_stable_name`, `brand_qr_status` (`downloaded` / `failed`
-  / `disabled` / `fallback`), `brand_qr_error`, `brand_qr_data_url`,
-  `brand_qr_must_render_reason`, `brand_qr_render_action`. Read the
-  path with the IDE's `Read` tool so the human sees the picture.
-- `itpay services checkout --json` — same brand QR fields, plus
-  `next_action: "open_human_checkout"` and the checkout-scoped
-  `display_token`. Agents must show this ItPay checkout QR/URL to the
-  human and must not call `itpay pay` for the normal buyer flow.
-- Markdown (Trae / Codex / Claude Code) — inlines a `data:image/png;base64,...`
-  copy of the picture plus a `[ATTACH] IDE image` reference block that
-  points at the canonical local path and mirrors.
-- Terminal — prints `Branded QR: /path/...png` and `QR mirrors: ...`;
-  iTerm inline image renders the same file when the session supports it.
-- Telegram — the `ide_image_attach` block on `presentation.ide_image_attach`
-  carries `status`, `local_path`, `mirrors`, `mime_type`, `source`,
-  `caption`, `error` (when failed), `must_render_reason`, and a
-  step-by-step `instructions` array.
-- Feishu / Lark — same `ide_image_attach` block on the
-  `message.ide_image_attach` envelope.
-
-Disable the contract with `ITPAY_IDE_IMAGE_ATTACH=0` for runners on a
-read-only filesystem. The plan carries `status: "disabled"` instead
-of `status: "downloaded"` and no PNG is downloaded.
-
-## Layout
-
-- `src/main.ts` — `commander` entrypoint, command registration
-- `src/client/` — HTTP/JSON client and DTOs
-- `src/commands/` — one file per command family
-- `src/render/` — terminal formatting
-  - `plan.ts` — `RenderPlan` contract shared by all renderers
-  - `qr.ts` — local QR + format selection
-  - `terminal.ts`, `markdown.ts`, `plain_chat.ts`, `telegram.ts`, `feishu.ts` — per-host renderers
-  - `index.ts` — `dispatchRender()` picks the right renderer
-  - `sink.ts` — `OutputSink` so tests can silence stdout
-- `src/state/` — local CLI config, cart session, client context
-- `tests/` — node:test smoke test + in-process mock backend
-
-## Rules
-
-- commands orchestrate user intent only
-- render code must not issue HTTP calls
-- keep API access under `src/client/`
-- persist checkout-scoped `display_token` and last server handles only in the owner-only local cart session file
-- the default `buy` command must not create a payment intent unless `--pay` is explicit
-- the default `services checkout` command must render the ItPay
-  checkout handoff; provider payment intents are created by the human
-  checkout page, not by the agent
-- a renderer must consume the brand QR the V3 backend hands back
-  (`qr_payload` / `qr_png_url` / `mobile_wallet_url`) and only
-  self-generate a QR for `auth_qr` / `checkout_qr` with the explicit
-  `--qr-file` opt-in
+- `ITPAY_BACKEND_URL`: deliberate API override.
+- `ITPAY_AGENT_TYPE`: stable alternative to global `--agent-type`.
+- `ITPAY_BEARER_TOKEN`: account-scoped Buyer session for account-only commands such as `orders`.
+- `ITPAY_CART_SESSION_PATH`: local recovery-state path override.
+- `ITPAY_CURRENCY`: ordinary Cart currency, default `CNY`.
+- `ITPAY_IDEMPOTENCY_KEY`: explicit operation key for deterministic testing; normal use persists operation IDs automatically.
+- `ITPAY_IDE_IMAGE_ATTACH=0`: disable local Checkout image download when the runtime filesystem is read-only.
+- `ITPAY_IDE_IMAGE_DIR_OVERRIDE`: override the local Checkout image directory.
+
+Provider credentials, Buyer identity, payment provider choice, amount, refund policy, quota, grant scope, and delivery access are never client-owned environment settings.
+
+## Development
+
+```bash
+npm run lint
+npm test
+npm run test:package
+npm run pack:dry-run
+```
+
+Source boundaries:
+
+- `src/main.ts`: parser and error-envelope wiring.
+- `src/client`: typed HTTP access.
+- `src/commands`: command orchestration and public output projection.
+- `src/render`: Host presentation only; no business HTTP.
+- `src/state`: local Device Authority, idempotency journal, and recovery handles.
+- `docs/cli-reference`: normative command contracts.
+- `docs/agent/buyer`: packaged progressive workflow guidance.

package/dist/src/client/backend.js

@@ -32,17 +32,16 @@ export class BackendClient {
         return this.http.delete(`/v1/carts/${encodeURIComponent(cartID)}`);
     }
     // --- Checkout ---
-    createCheckout(input) {
-        return this.http.post("/v1/checkouts", input);
+    createCheckout(input, idempotencyKey) {
+        return this.http.post("/v1/checkouts", input, idempotencyKey ? { idempotencyKey } : undefined);
     }
     getCheckoutPresentation(checkoutID, displayToken) {
         const qs = new URLSearchParams({ display_token: displayToken });
         return this.http.get(`/v1/checkouts/${encodeURIComponent(checkoutID)}/presentation?${qs}`);
     }
     // --- Payment intents ---
-    createPaymentIntent(checkoutID, input, idempotencyKey) {
-        const options = idempotencyKey ? { idempotencyKey } : {};
-        return this.http.post(`/v1/checkouts/${encodeURIComponent(checkoutID)}/payment-intents`, input, options);
+    createPaymentIntent(checkoutID, input) {
+        return this.http.post(`/v1/checkouts/${encodeURIComponent(checkoutID)}/payment-intents`, input);
     }
     // --- SSE streaming ---
     streamCheckoutEvents(checkoutID, displayToken, onEvent, signal) {
@@ -54,6 +53,9 @@ export class BackendClient {
     getOrder(orderID) {
         return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}`);
     }
+    getOrderDeliveryAccess(orderID) {
+        return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/delivery-access`);
+    }
     listAccountOrders(limit, status, bearer) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (status) {
@@ -62,10 +64,19 @@ export class BackendClient {
         return this.http.get(`/v1/me/orders?${qs}`, bearer ? { bearer } : {});
     }
     // --- Refund ---
-    createRefund(orderID, input, idempotencyKey) {
-        const options = idempotencyKey ? { idempotencyKey } : {};
+    createRefund(orderID, input, bearer, idempotencyKey) {
+        const options = { ...(bearer ? { bearer } : {}), ...(idempotencyKey ? { idempotencyKey } : {}) };
         return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/refunds`, input, options);
     }
+    listOrderRefunds(orderID) {
+        return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/refunds`);
+    }
+    getRefund(refundRequestID) {
+        return this.http.get(`/v1/refunds/${encodeURIComponent(refundRequestID)}`);
+    }
+    cancelRefund(refundRequestID, reason = "buyer_cancelled") {
+        return this.http.post(`/v1/refunds/${encodeURIComponent(refundRequestID)}/cancel`, { reason });
+    }
     // --- Service Execution ---
     startServiceExecution(input) {
         return this.http.post("/v1/service-executions", input);
@@ -79,14 +90,21 @@ export class BackendClient {
     createServiceExecutionCheckout(serviceExecutionID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/checkout`, input);
     }
+    prepareServiceQuote(serviceExecutionID, input) {
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/quotes`, input);
+    }
     getServiceExecution(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}`);
     }
     listServiceExecutions(limit = 50) {
         return this.http.get(`/v1/service-executions?limit=${limit}`);
     }
-    listServiceExecutionEvents(serviceExecutionID) {
-        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/events`);
+    listServiceExecutionEvents(serviceExecutionID, afterSequence = 0, limit = 50) {
+        const query = new URLSearchParams({
+            after_sequence: String(afterSequence),
+            limit: String(limit),
+        });
+        return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/events?${query}`);
     }
     getGrantedServiceResult(serviceExecutionID) {
         return this.http.get(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/granted-result`);

package/dist/src/commands/buy.js

@@ -11,54 +11,55 @@
 import { operationID } from "../state/config.js";
 import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
-import { dispatchInteractionRequest } from "../render/interaction.js";
-import { ensureIdeImageAttach, readFileAsDataURL } from "../render/ide.js";
+import { platformKeyForHost } from "../render/plan.js";
+import { ensureIdeImageAttach } from "../render/ide.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
+import { formatMoney } from "../render/output.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
     if (err) {
         throw new Error(`${err.code}: ${err.message}`);
     }
     const snap = options.cartSession.show();
-    if (!options.cartID && snap.items.length === 0) {
-        throw new Error("cart is empty; add an item with `itpay cart add` first");
+    const resumableCartID = !options.cartID && snap.items.length === 0 ? snap.lastCartID : undefined;
+    if (!options.cartID && !resumableCartID && snap.items.length === 0) {
+        throw new CommandContractError("cart_empty", "no local draft or canonical cart is available", "没有可购买的普通 Cart；从已发布目录选择项目，不要猜测 item、variant 或 offer。", [{ command: "itpay catalog list --json", reason: "读取已发布项目" }]);
     }
     const missingContactFields = findMissingContactFields(options.contact, options.requiredContactFields ?? []);
     if (missingContactFields.length > 0) {
-        const interactionRequest = buildMissingContactInteractionRequest(missingContactFields);
-        await dispatchInteractionRequest(options.host, interactionRequest, {
-            ...(options.isTTY !== undefined ? { isTTY: options.isTTY } : {}),
-            ...(options.target ? { target: options.target } : {}),
-            ...(options.output ? { output: options.output } : {}),
-        });
-        return {
-            kind: "interaction_requested",
-            interactionRequest,
-        };
+        throw new CommandContractError("missing_contact", `missing required contact fields: ${missingContactFields.join(", ")}`, `向用户询问 ${missingContactFields.join(" 和 ")}，然后在同一 buy 命令补充对应 contact 参数；禁止编造。`, [{ command: "itpay buy --help", reason: "查看 contact 参数" }]);
     }
     let cart;
-    if (options.cartID) {
-        cart = await backend.getCart(options.cartID);
+    if (options.cartID || resumableCartID) {
+        cart = await backend.getCart(options.cartID ?? resumableCartID);
     }
     else {
         const request = options.cartSession.toCreateCartRequest();
         request.client_context = {
             host: options.host,
             target: options.target,
-            agent_device_id: options.cartSession.ensureAgentDeviceID(config.agentDeviceID),
         };
-        const agentDeviceID = options.cartSession.ensureAgentDeviceID(config.agentDeviceID);
-        request.agent_device_id = agentDeviceID;
         cart = await backend.createCart(request);
     }
+    const latestLine = cart.items[cart.items.length - 1];
+    options.cartSession.rememberServerCart({
+        cartID: cart.cart_id,
+        ...(latestLine?.cart_item_id ? { cartItemID: latestLine.cart_item_id } : {}),
+        ...(latestLine?.service_execution_id ? { serviceExecutionID: latestLine.service_execution_id } : {}),
+    });
+    const unquotedServiceLine = cart.items.find((item) => item.service_execution_id && !item.service_quote_lock_id);
+    if (unquotedServiceLine?.service_execution_id) {
+        throw new CommandContractError("service_quote_required", `cart ${cart.cart_id} contains an unquoted service-backed line`, "该服务项目尚未绑定 Quote Lock；回到来源 Execution 完成候选选择和报价。", [{ command: `itpay services next ${unquotedServiceLine.service_execution_id} --json`, reason: "读取当前合法动作" }]);
+    }
+    const idempotencyKey = await operationID(config, `checkout.create:${cart.cart_id}`);
     const checkoutRequest = {
         cart_id: cart.cart_id,
-        client_reference_id: options.clientReferenceID ?? await operationID(config, `checkout.create:${cart.cart_id}`),
+        client_reference_id: options.clientReferenceID ?? idempotencyKey,
         ...(options.contact ? { delivery_contact: options.contact } : {}),
     };
-    const checkout = await backend.createCheckout(checkoutRequest);
+    const checkout = await backend.createCheckout(checkoutRequest, idempotencyKey);
     options.cartSession.rememberCheckout({
-        cartID: cart.cart_id,
         checkoutID: checkout.checkout.checkout_id,
         displayToken: checkout.display_token,
         checkoutURL: tokenizedCheckoutURL(checkout.checkout_url, checkout.display_token, checkout.qr_payload),
@@ -77,7 +78,7 @@ export async function runBuy(backend, config, options) {
     let waitStatus = "skipped";
     if (options.pay) {
         const method = options.payMethod ?? "alipay";
-        paymentIntent = await backend.createPaymentIntent(checkoutID, { payment_method_type: method, display_token: displayToken }, await operationID(config, `payment.intent:${checkoutID}:${method}`));
+        paymentIntent = await backend.createPaymentIntent(checkoutID, { payment_method_type: method, display_token: displayToken });
         if (!options.jsonOutput) {
             process.stdout.write("\n--- payment intent ---\n");
             process.stdout.write(`  id:     ${paymentIntent.payment_intent_id}\n`);
@@ -124,34 +125,23 @@ export async function runBuy(backend, config, options) {
     });
     // --- Output ---
     if (options.jsonOutput) {
-        const jsonInput = {
-            checkout: { ...checkout, checkout_url: checkoutURL },
+        const envelope = buildBuyEnvelope({
             cart,
-            waitStatus,
+            checkoutID,
+            checkoutURL,
+            displayToken,
             plan,
-        };
-        if (paymentIntent) {
-            jsonInput.paymentIntent = paymentIntent;
-        }
-        if (plan.ideImageAttach) {
-            jsonInput.ideImageAttach = {
-                localPath: plan.ideImageAttach.localPath,
-                mirrors: plan.ideImageAttach.mirrors,
-                mimeType: plan.ideImageAttach.mimeType,
-                ...(plan.ideImageAttach.caption ? { caption: plan.ideImageAttach.caption } : {}),
-                mustRenderReason: plan.ideImageAttach.mustRenderReason,
-                status: plan.ideImageAttach.status,
-                ...(plan.ideImageAttach.error ? { error: plan.ideImageAttach.error } : {}),
-            };
-        }
-        const json = buildJSONOutput(jsonInput);
-        (options.output ?? ((line) => process.stdout.write(line + "\n")))(JSON.stringify(json, null, 2) + "\n");
+            waitStatus,
+            ...(checkout.qr_png_url ? { qrPNGURL: checkout.qr_png_url } : {}),
+            ...(paymentIntent ? { paymentIntent } : {}),
+        });
+        writeCommandEnvelope(envelope, { jsonOutput: true, ...(options.output ? { output: options.output } : {}) });
         return {
             kind: "checkout_rendered",
             plan,
             checkoutID,
             displayToken,
-            json,
+            envelope,
         };
     }
     // Text output — always render QR for non-JSON mode
@@ -173,6 +163,55 @@ export async function runBuy(backend, config, options) {
         displayToken,
     };
 }
+function buildBuyEnvelope(input) {
+    const verified = input.waitStatus === "verified";
+    const platform = platformKeyForHost(input.plan.host);
+    const handoff = { url: input.checkoutURL };
+    if (input.plan.ideImageAttach?.status === "downloaded" && input.plan.ideImageAttach.localPath) {
+        handoff.qr_local_path = input.plan.ideImageAttach.localPath;
+    }
+    if (platform === "markdown") {
+        handoff.markdown = buildAgentChatHandoff(input.plan).markdown;
+    }
+    else if (platform === "plain_chat" && input.qrPNGURL) {
+        handoff.qr_image_url = input.qrPNGURL;
+    }
+    const result = {
+        checkout_id: input.checkoutID,
+        payment: verified ? "verified" : "pending",
+        amount: formatMoney(input.cart.amount_minor, input.cart.currency),
+        item_count: input.cart.items.length,
+        ...(input.paymentIntent ? {
+            payment_intent_id: input.paymentIntent.payment_intent_id,
+            payment_intent_status: input.paymentIntent.status,
+        } : {}),
+        ...(input.waitStatus === "timeout" ? { wait_status: "timeout" } : {}),
+    };
+    if (verified) {
+        return {
+            status: "payment_event_observed",
+            result,
+            instruction: "已观察到付款确认事件；读取同一 Checkout 的权威完成状态，不要再次付款。",
+            next: { command: `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "读取订单和履约句柄" },
+            recovery: [],
+        };
+    }
+    return {
+        status: "human_checkout_required",
+        result,
+        handoff,
+        instruction: buyHandoffInstruction(platform),
+        next: { command: `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`, reason: "稍后查询同一笔 Checkout 状态" },
+        recovery: [],
+    };
+}
+function buyHandoffInstruction(platform) {
+    if (platform === "markdown")
+        return "把 handoff.markdown 原样发送到当前桌面对话；二维码和链接可见后等待用户操作，不要创建新 Checkout。";
+    if (platform === "terminal")
+        return "在用户可见终端展示 handoff 中的付款入口，然后等待用户操作；不要创建新 Checkout。";
+    return "把 handoff.url 和可用二维码附件发送给用户，然后等待用户操作；不要创建新 Checkout。";
+}
 // --- SSE wait for payment verification ---
 async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec) {
     return new Promise((resolve) => {
@@ -194,81 +233,11 @@ async function waitForPaymentSSE(backend, checkoutID, displayToken, timeoutSec)
         });
     });
 }
-export function buildJSONOutput(input) {
-    const output = {
-        kind: "checkout_created",
-        checkout_id: input.checkout.checkout.checkout_id,
-        checkout_url: input.checkout.checkout_url,
-        display_token: input.checkout.display_token,
-        qr_payload: input.checkout.qr_payload,
-        checkout_status: input.checkout.checkout.status,
-        wait_status: input.waitStatus,
-    };
-    if (input.checkout.qr_png_url) {
-        output.qr_png_url = input.checkout.qr_png_url;
-    }
-    const serviceExecutions = input.cart?.items
-        .filter((item) => item.service_execution_id)
-        .map((item) => ({
-        service_execution_id: item.service_execution_id,
-        ...(item.service_capability_id ? { service_capability_id: item.service_capability_id } : {}),
-        ...(item.title ? { title: item.title } : {}),
-    }));
-    if (serviceExecutions && serviceExecutions.length > 0) {
-        output.service_executions = serviceExecutions;
-    }
-    if (input.paymentIntent) {
-        output.payment_intent_id = input.paymentIntent.payment_intent_id;
-        output.payment_status = input.paymentIntent.status;
-        if (input.paymentIntent.action) {
-            const pa = {};
-            if (input.paymentIntent.action.qr_image_url)
-                pa.qr_image_url = input.paymentIntent.action.qr_image_url;
-            if (input.paymentIntent.action.mobile_wallet_url)
-                pa.mobile_wallet_url = input.paymentIntent.action.mobile_wallet_url;
-            output.payment_action = pa;
-        }
-        output.kind = "payment_handoff_required";
-    }
-    if (input.waitStatus === "verified") {
-        output.kind = "payment_verified";
-    }
-    if (input.ideImageAttach) {
-        output.brand_qr_status = input.ideImageAttach.status;
-        if (input.ideImageAttach.localPath) {
-            output.brand_qr_local_path = input.ideImageAttach.localPath;
-            const dataURL = readFileAsDataURL(input.ideImageAttach.localPath, input.ideImageAttach.mimeType);
-            if (dataURL)
-                output.brand_qr_data_url = dataURL;
-            const stableName = input.ideImageAttach.localPath.split("/").pop();
-            if (stableName)
-                output.brand_qr_stable_name = stableName;
-        }
-        if (input.ideImageAttach.mirrors.length > 0) {
-            output.brand_qr_mirrors = [...input.ideImageAttach.mirrors];
-        }
-        output.brand_qr_mime_type = input.ideImageAttach.mimeType;
-        if (input.ideImageAttach.caption)
-            output.brand_qr_caption = input.ideImageAttach.caption;
-        if (input.ideImageAttach.error)
-            output.brand_qr_error = input.ideImageAttach.error;
-        output.brand_qr_must_render_reason = input.ideImageAttach.mustRenderReason;
-        output.brand_qr_render_action = "agent_must_read_local_path_into_ide_chat";
-    }
-    output.next = input.waitStatus === "verified"
-        ? "itpay orders"
-        : `itpay checkout --id ${input.checkout.checkout.checkout_id} --token ${input.checkout.display_token}`;
-    if (input.plan)
-        output.agent_action = buildAgentChatHandoff(input.plan);
-    return output;
-}
 // --- checkout QR plan ---
 export function buildCheckoutQRPlan(input) {
     const summary = `Scan the QR or open ${input.checkoutURL} to start the human checkout flow.`;
     const isPayment = input.paymentIntentID != null;
-    const afterCommand = isPayment
-        ? `itpay checkout --id ${input.checkoutID} --token ${input.displayToken}`
-        : `itpay checkout --id ${input.checkoutID} --token ${input.displayToken}`;
+    const afterCommand = `itpay checkout --id ${input.checkoutID} --token ${input.displayToken} --json`;
     const platform = {
         text: summary,
         links: [
@@ -307,23 +276,6 @@ export function buildCheckoutQRPlan(input) {
     return plan;
 }
 // --- contact field interaction ---
-export function buildMissingContactInteractionRequest(fields) {
-    return {
-        kind: "input",
-        id: "collect_delivery_contact",
-        title: "Collect buyer contact",
-        prompt: "Before creating the checkout, ask the buyer to provide the missing contact details.",
-        fields: fields.map((field) => ({
-            id: field,
-            label: field === "email" ? "Email" : "Phone number",
-            inputType: field === "email" ? "email" : "phone",
-            required: true,
-            placeholder: field === "email" ? "buyer@example.com" : "+86 138...",
-            description: field === "email" ? "Used for receipts or delivery follow-up." : "Used when the order requires buyer verification.",
-        })),
-        submitLabel: "Submit contact",
-    };
-}
 function findMissingContactFields(contact, fields) {
     return fields.filter((field) => {
         const value = contact?.[field];