@itpay/cli 2.0.5 → 2.0.7

package/README.md

@@ -4,9 +4,11 @@ The official V3 CLI for Agent-driven ItPay service discovery, checkout, delivery
 
 ```bash
 npm install -g @itpay/cli
+itpay readyz --json
+itpay skill show itpay-buyer --json
 itpay install --json
 itpay --agent-type codex-desktop readyz --json
-itpay --agent-type codex-desktop catalog list --json
+# follow next.command: typed skill show, then catalog list
 ```
 
 The default API is `https://app.itpay.ai`. Set `ITPAY_BACKEND_URL` only for an intentional test or local environment.
@@ -38,7 +40,9 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 | `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.
+`--agent-type` identifies the stable runtime and registered Agent instance. Every returned ItPay command preserves it. Different windows or chats of the same type reuse one Agent Instance; they are not separate identities. `--host` only selects the human presentation surface, and `--target` only routes output to a Host destination. Use `itpay install <agent_type> --json` for the exact responsibility.
+
+The local installation keeps one Ed25519 private key. Each normalized Backend API base URL (`dev`, `test`, `app`, or local) has an independent server device registration, quota lineage, Agent instances, and sessions. A rejected session is renewed and the same request is retried once; revoked v2 registrations are never silently replaced.
 
 ## Command Families
 
@@ -50,7 +54,7 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 - `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.
+- `install`, `skill show`, `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.
@@ -67,7 +71,7 @@ itpay --agent-type <agent_type> services checkout <service_execution_id> --resum
 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.
+The local `~/.itpay-v3` directory stores one owner-only signing key, Backend-scoped Device registrations and Agent instances, idempotency operations, and recovery handles. Backend state remains authoritative. Do not delete or rotate this identity to recover quota.
 
 ## Environment
 

package/dist/src/client/http.js

@@ -17,6 +17,7 @@ export class HttpClient {
     fetchImpl;
     defaultHeaders;
     requestAuthorizer;
+    recoverAuthorization;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, "");
         this.fetchImpl = config.fetchImpl ?? globalThis.fetch;
@@ -26,35 +27,40 @@ export class HttpClient {
             ...(config.defaultHeaders ?? {}),
         };
         this.requestAuthorizer = config.requestAuthorizer;
+        this.recoverAuthorization = config.recoverAuthorization;
     }
     async request(path, options = {}) {
         const url = path.startsWith("http") ? path : this.baseURL + path;
-        const headers = { ...this.defaultHeaders };
         const method = options.method ?? "GET";
         const body = options.body !== undefined ? JSON.stringify(options.body) : "";
-        if (this.requestAuthorizer) {
-            Object.assign(headers, await this.requestAuthorizer({ method, path: new URL(url).pathname + new URL(url).search, body }));
+        const requestPath = new URL(url).pathname + new URL(url).search;
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const headers = { ...this.defaultHeaders };
+            if (this.requestAuthorizer) {
+                Object.assign(headers, await this.requestAuthorizer({ method, path: requestPath, body }));
+            }
+            if (options.bearer)
+                headers.Authorization = `Bearer ${options.bearer}`;
+            if (options.idempotencyKey)
+                headers["Idempotency-Key"] = options.idempotencyKey;
+            const response = await this.fetchImpl(url, {
+                method,
+                headers,
+                ...(options.body !== undefined ? { body } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+            });
+            const text = await response.text();
+            const parsed = text.length > 0 ? safeParseJson(text) : undefined;
+            if (response.ok)
+                return parsed;
+            const error = new HttpError(response.status, parsed, `HTTP ${response.status}`);
+            if (attempt === 0 && error.status === 401 && error.code === "agent_device_session_required" && this.recoverAuthorization) {
+                await this.recoverAuthorization();
+                continue;
+            }
+            throw error;
         }
-        if (options.bearer) {
-            headers.Authorization = `Bearer ${options.bearer}`;
-        }
-        if (options.idempotencyKey) {
-            headers["Idempotency-Key"] = options.idempotencyKey;
-        }
-        const requestInit = {
-            method,
-            headers,
-            ...(options.body !== undefined ? { body } : {}),
-            ...(options.signal ? { signal: options.signal } : {}),
-        };
-        const response = await this.fetchImpl(url, requestInit);
-        const text = await response.text();
-        const parsed = text.length > 0 ? safeParseJson(text) : undefined;
-        if (!response.ok) {
-            const errPayload = parsed;
-            throw new HttpError(response.status, errPayload, `HTTP ${response.status}`);
-        }
-        return parsed;
+        throw new Error("unreachable HTTP retry state");
     }
     get(path, options = {}) {
         return this.request(path, { ...options, method: "GET" });

package/dist/src/commands/catalog.js

@@ -4,6 +4,7 @@ export async function runCatalogList(backend, options = {}) {
     const services = manifest.manifest.items.map(summarizeService);
     const firstServiceID = manifest.manifest.items.find((item) => item.service_id)?.service_id;
     const empty = services.length === 0;
+    const jsonFlag = options.jsonOutput ? " --json" : "";
     writeCommandEnvelope({
         status: empty ? "catalog_empty" : "listed",
         result: { catalog_version: manifest.version, services },
@@ -11,9 +12,9 @@ export async function runCatalogList(backend, options = {}) {
             ? "当前没有已发布服务；稍后重试，不要猜测 service_id。"
             : "向用户解释主服务、辅助步骤和价格；得到用户意图后再启动对应 service_id。",
         next: empty
-            ? { command: "itpay catalog list", reason: "稍后重新读取已发布目录" }
+            ? { command: `itpay catalog list${jsonFlag}`, reason: "稍后重新读取已发布目录" }
             : {
-                command: `itpay services start ${services.length === 1 && firstServiceID ? firstServiceID : "<service_id>"}`,
+                command: `itpay services start ${services.length === 1 && firstServiceID ? firstServiceID : "<service_id>"}${jsonFlag}`,
                 reason: "启动用户选择的服务",
             },
         recovery: [],

package/dist/src/commands/checkout.js

@@ -20,8 +20,8 @@ export async function runCheckoutPresentation(backend, options) {
         return;
     }
     const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
-    const qrPNGURL = presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken);
-    const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken}`;
+    const qrPNGURL = absolutePublicURL(options.baseURL, presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken));
+    const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`;
     const plan = buildCheckoutQRPlan({
         host,
         checkoutID: options.checkoutID,
@@ -61,19 +61,20 @@ function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand) {
     if (platform === "markdown") {
         handoff.markdown = buildAgentChatHandoff(plan).markdown;
     }
-    else if (platform === "plain_chat" && presentation.qr_png_url) {
-        handoff.qr_image_url = presentation.qr_png_url;
+    else if (platform === "plain_chat" && plan.preferredQRSources[0]) {
+        handoff.qr_image_url = plan.preferredQRSources[0];
     }
+    const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
     return {
         status: "human_checkout_required",
         result: {
             checkout_id: presentation.checkout.checkout_id,
             payment: "pending",
-            amount: formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency),
+            amount,
         },
         handoff,
-        instruction: pendingInstruction(platform),
-        next: { command: nextCommand, reason: "稍后查询同一笔 Checkout 状态" },
+        instruction: pendingInstruction(platform, amount),
+        next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
         recovery: [],
     };
 }
@@ -96,9 +97,9 @@ function terminalCheckoutEnvelope(presentation) {
     const recovery = [];
     if (payment === "verified") {
         status = "completed";
-        instruction = "付款已确认，不要再次展示付款二维码。";
+        instruction = "Backend 已确认这笔付款。不要再次展示付款入口，不要调用 pay，不要创建新 Checkout 或 Execution。现在只执行 next.command，读取同一 Execution 的履约结果。";
         next = serviceExecutionIDs.length === 1
-            ? { command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "读取履约状态" }
+            ? { command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "读取同一笔已付款 Service Execution" }
             : presentation.completed_order_id
                 ? { command: `itpay order ${presentation.completed_order_id}`, reason: "读取已创建订单" }
                 : { command: "itpay orders", reason: "恢复已付款订单" };
@@ -122,12 +123,12 @@ function checkoutNeedsHumanHandoff(status) {
 function checkoutPlainResult(result) {
     return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
 }
-function pendingInstruction(platform) {
+function pendingInstruction(platform, amount) {
     if (platform === "markdown")
-        return "把 handoff.markdown 原样发送到当前桌面对话；二维码和链接可见后等待用户操作，不要创建新 Checkout。";
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、链接和金额 ${amount} 已对用户可见，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
     if (platform === "terminal")
-        return "在用户可见终端展示二维码和付款链接，然后等待用户操作；不要创建新 Checkout。";
-    return "把付款链接和可用二维码附件发送给用户，然后等待用户操作；不要创建新 Checkout。";
+        return `Backend 尚未确认付款。在用户可见终端展示当前同一 Checkout 的二维码、链接和金额 ${amount}，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
+    return `Backend 尚未确认付款。把 handoff.url 作为可点击链接发送给用户，优先把 handoff.qr_local_path 作为图片附件发送，不能发送本地附件时使用 handoff.qr_image_url，并说明金额 ${amount}，然后停止等待。不要声称付款成功，不要创建新 Checkout、Execution 或 Payment Intent。稍后仍然只执行 next.command 查询这一笔 Checkout。`;
 }
 function formatMoney(amountMinor, currency) {
     return `${(amountMinor / 100).toFixed(2)} ${currency}`;
@@ -143,3 +144,12 @@ function checkoutQRPNGURL(baseURL, checkoutID, displayToken) {
 function publicRoot(baseURL) {
     return (baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
 }
+function absolutePublicURL(baseURL, value) {
+    try {
+        const root = publicRoot(baseURL);
+        return new URL(value, `${root}/`).toString();
+    }
+    catch {
+        return value;
+    }
+}

package/dist/src/commands/guidance.js

@@ -1,5 +1,6 @@
 import { HttpError } from "../client/http.js";
 import { resolveOutput } from "../render/sink.js";
+import { declaredAgentType, qualifyItPayCommand } from "../state/agent_type.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
@@ -17,12 +18,14 @@ export class CommandContractError extends Error {
 }
 export function writeCommandEnvelope(value, options = {}) {
     const out = resolveOutput(options.output);
+    const agentType = options.agentType ?? declaredAgentType();
+    const qualified = qualifyEnvelope(value, agentType);
     if (options.jsonOutput) {
-        out(JSON.stringify(value, null, 2) + "\n");
+        out(JSON.stringify(qualified, null, 2) + "\n");
         return;
     }
-    out(`${value.status}\n`);
-    const facts = "result" in value ? value.result : value.error;
+    out(`${qualified.status}\n`);
+    const facts = "result" in qualified ? qualified.result : qualified.error;
     if (options.plainResult) {
         for (const line of options.plainResult)
             out(`${line}\n`);
@@ -32,17 +35,17 @@ export function writeCommandEnvelope(value, options = {}) {
             out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
     }
-    if ("handoff" in value && value.handoff) {
-        for (const [key, fact] of Object.entries(value.handoff)) {
+    if ("handoff" in qualified && qualified.handoff) {
+        for (const [key, fact] of Object.entries(qualified.handoff)) {
             out(`handoff.${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
         }
     }
-    out(`instruction: ${value.instruction}\n`);
-    if (value.next)
-        out(`next: ${value.next.command}\n`);
-    if (value.recovery.length > 0) {
+    out(`instruction: ${qualified.instruction}\n`);
+    if (qualified.next)
+        out(`next: ${qualified.next.command}\n`);
+    if (qualified.recovery.length > 0) {
         out("recovery:\n");
-        for (const action of value.recovery) {
+        for (const action of qualified.recovery) {
             out(`  - ${action.command}\n`);
             out(`    reason: ${action.reason}\n`);
         }
@@ -56,6 +59,7 @@ export function attachAgentGuidance(payload, guidance) {
 }
 export function printAgentGuidance(guidance, output) {
     const out = resolveOutput(output);
+    const agentType = declaredAgentType();
     out(`${guidance.summary}\n`);
     if (guidance.visible_results?.length) {
         out("results:\n");
@@ -75,7 +79,7 @@ export function printAgentGuidance(guidance, output) {
         out("next actions:\n");
         for (const action of guidance.next_actions) {
             out(`  - ${action.label}\n`);
-            out(`    ${action.command}\n`);
+            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
             if (action.requires_human)
                 out("    requires human confirmation\n");
             if (action.reason)
@@ -86,10 +90,20 @@ export function printAgentGuidance(guidance, output) {
         out("recovery:\n");
         for (const action of guidance.recovery) {
             out(`  - ${action.label}\n`);
-            out(`    ${action.command}\n`);
+            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
         }
     }
 }
+function qualifyEnvelope(value, agentType) {
+    return {
+        ...value,
+        next: value.next ? { ...value.next, command: qualifyItPayCommand(value.next.command, agentType) } : null,
+        recovery: value.recovery.map((action) => ({
+            ...action,
+            command: qualifyItPayCommand(action.command, agentType),
+        })),
+    };
+}
 export function buildCartGuidance(cart, serviceModel) {
     const serviceLine = latestServiceLine(cart);
     if (serviceLine?.service_execution_id) {
@@ -225,7 +239,7 @@ export function buildServiceHandleGuidance(serviceExecutionID, checkoutCapabilit
 export function errorRecoveryActions(error) {
     if (!(error instanceof HttpError))
         return [];
-    if (error.code === "agent_identity_required" || error.code === "agent_device_session_required") {
+    if (error.code === "agent_identity_required") {
         return [
             {
                 id: "inspect_agent_setup",
@@ -234,6 +248,16 @@ export function errorRecoveryActions(error) {
             },
         ];
     }
+    if (error.code === "agent_device_session_required") {
+        return [
+            {
+                id: "read_agent_session_rules",
+                label: "Read identity and session recovery rules",
+                command: "itpay skill show itpay-buyer --json",
+                reason: "The CLI already attempted one automatic session renewal; do not rotate identity or loop retries.",
+            },
+        ];
+    }
     if (error.code === "quota_exhausted" || error.code === "checkout_required") {
         return [
             {

package/dist/src/commands/readyz.js

@@ -4,9 +4,9 @@ export async function runReadyz(backend, options = {}) {
     const response = await backend.readyz();
     writeCommandEnvelope({
         status: response.status,
-        result: { backend: "available" },
-        instruction: "ItPay 可用，可以读取服务目录。",
-        next: { command: "itpay catalog list", reason: "发现可用服务" },
+        result: { backend: "available", ...(options.agentType ? { agent_type: options.agentType } : {}) },
+        instruction: "ItPay 可用；先完整读取内置 Buyer Skill，再开始服务流程。",
+        next: { command: "itpay skill show itpay-buyer --json", reason: "加载完整操作与安全规则" },
         recovery: [],
     }, options);
 }