@itpay/cli 2.1.41 → 2.1.44

package/dist/src/main.js

@@ -1,9 +1,14 @@
+import { runAftercareList, runAftercareCreate, runAftercareGet, runAftercareRespond } from "./commands/aftercare.js";
+import { agentAuth } from "./state/account_auth.js";
+import { registerSell } from "./sell/commands.js";
+import { readFileSync as readWorkflowInputFile, statSync as statWorkflowInputFile } from "node:fs";
+import { runServicesRun } from "./commands/services.js";
 // V3 CLI entrypoint. Each command maps 1:1 to a route family in
 // services/backend/internal/httpapi/handlers/*.go. Commands only
 // orchestrate; HTTP and rendering live in src/client and src/render.
 import { Command } from "commander";
 import { BackendOverrideError, API_CONTRACT_REVISION, CLI_VERSION, cliDistribution, loadConfig, cartSessionPath, newBackendClient } from "./state/config.js";
-import { DeviceAuthority, DeviceAuthorizationError, DeviceStateError } from "./state/device_authority.js";
+import { DeviceAuthority, DeviceAuthorizationError, DeviceLockBusyError, DeviceStateError } from "./state/device_authority.js";
 import { CartSession } from "./state/cart_session.js";
 import { defaultHostForAgentType, normalizeHost, validateContext } from "./state/client_context.js";
 import { HttpError } from "./client/http.js";
@@ -21,11 +26,11 @@ import { runCancelRefund, runGetRefund, runListRefunds, runRefund, runWatchRefun
 import { runCartAdd, runCartAddQuoteServer, runCartAddServer, runCartAbandonServer, runCartClear, runCartNext, runCartRemove, runCartRemoveServer, runCartShow, runCartShowServer, } from "./commands/cart.js";
 import { CommandContractError, errorRecoveryActions, printErrorRecovery, writeCommandEnvelope } from "./commands/guidance.js";
 import { runDocsList, runDocsShow, runDocsSearch } from "./commands/docs.js";
-import { runInstall } from "./commands/install.js";
+import { INSTALL_AGENT_TYPES, runInstall } from "./commands/install.js";
 import { runSkillShow } from "./commands/skill.js";
 import { runNext } from "./commands/next.js";
 import { runVaultAccess, runVaultList, runVaultRead } from "./commands/vault.js";
-import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
+import { collectOption, parseKeyValueList, runServicesAction, runServicesCheckout, runServicesEvents, runServicesGet, runServicesInvoke, runServicesList, runServicesNext, runServicesPage, runServicesReadResult, runServicesQuote, runServicesStart, } from "./commands/services.js";
 const program = new Command();
 program
     .name("itpay")
@@ -112,6 +117,7 @@ function reportCLIError(error, contract) {
     const backendOverrideError = error instanceof BackendOverrideError ? error : undefined;
     const deviceError = error instanceof DeviceAuthorizationError ? error : undefined;
     const stateError = error instanceof DeviceStateError ? error : undefined;
+    const lockError = error instanceof DeviceLockBusyError ? error : undefined;
     const transportError = error instanceof HttpTransportError ? error : undefined;
     const httpRecovery = errorRecoveryActions(error).map((action) => ({
         command: action.command,
@@ -130,31 +136,42 @@ function reportCLIError(error, contract) {
     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 ? [{
+    const deviceKeyResettable = Boolean(deviceError && (deviceError.code === "agent_device_key_rotated" ||
+        deviceError.code === "agent_device_key_conflict"));
+    const deviceRecovery = deviceError ? [
+        {
             command: "itpay skill show itpay --json",
             reason: "读取 ItPay 身份边界；该错误需要用户或运营恢复 Backend 登记，不能通过换类型或删除本地身份绕过",
-        }] : [];
-    const stateRecovery = stateError ? [{
-            command: "itpay skill show itpay --json",
-            reason: "读取 Device 状态边界；修复当前 Host 的持久写权限后重试原命令",
+        },
+    ] : [];
+    const stateRecovery = [];
+    const lockRecovery = lockError ? [{
+            command: "itpay device repair-lock --json",
+            reason: "检查锁持有者；只回收已退出进程留下的锁，不改变设备身份",
         }] : [];
     const authorizationInstruction = stateError
-        ? "当前运行环境无法写入 owner-only Device 状态；请保持同一 Node、CLI 和 Agent Type，在允许持久写入 ~/.itpay-v3 的执行环境中重试。不要手工创建 lock、删除 identity 或换运行时碰运气。"
-        : error instanceof HttpError && error.code === "agent_device_session_required"
-            ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
-            : deviceError?.code === "agent_device_revoked"
-                ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
-                : deviceError
-                    ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
-                    : undefined;
-    if (contract || commandError || backendOverrideError) {
+        ? `本地设备状态操作未完成：${stateError.operation}（${stateError.causeCode}，来源 ${stateError.source}）。保持原身份和已有授权；由环境负责人核对该操作、锁持有者和宿主返回。权限错误才检查读写权限；未知操作结果先核对现场，不盲目重试，不删除身份或绕过宿主保护。`
+        : lockError
+            ? "本地身份锁占用或安全转换未完成。执行 recovery 核对；活跃持有者需等待，遗留转换需环境负责人检查。不能仅凭等待时间删锁或重建身份。"
+            : error instanceof HttpError && error.code === "agent_device_session_required"
+                ? "CLI 已自动续期并重试同一请求一次，仍被拒绝；停止重试，不要切换 Agent Type 或旋转身份。"
+                : deviceError?.code === "agent_device_revoked"
+                    ? "Backend 已撤销当前 Device 登记；CLI 没有自动创建替代身份。停止重试并请用户或运营恢复登记。"
+                    : deviceError?.enrollmentFailed && deviceError.status === 500
+                        ? "服务端未能完成设备登记；保持原密钥和Agent Type，说明系统故障，待服务端恢复后继续原任务。不要重置身份。"
+                        : deviceKeyResettable
+                            ? "服务端拒绝当前设备私钥登记（轮换或冲突）。停止自动恢复；换钥会放弃旧身份，旧执行访问不会迁移。仅用户或运营明确决定放弃旧身份后，按 device reset-key 帮助执行。"
+                            : deviceError
+                                ? "Device 身份验证失败；停止重试，不要切换 Agent Type、删除状态或旋转私钥。"
+                                : undefined;
+    if (contract || commandError || backendOverrideError || lockError || stateError) {
         writeCommandEnvelope({
             status: "error",
             error: {
-                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
+                code: incompatible ? "backend_contract_incompatible" : backendOverrideError?.code ?? commandError?.code ?? (error instanceof HttpError ? error.code : transportError?.code ?? stateError?.code ?? lockError?.code ?? deviceError?.code ?? contract?.code ?? "command_failed"),
                 message: error instanceof Error ? error.message : String(error),
             },
-            ...(incompatible && error instanceof HttpError ? {
+            ...(stateError ? { result: { failure_stage: "local_device_state", operation: stateError.operation, cause_code: stateError.causeCode, source: stateError.source } } : commandError?.result ? { result: commandError.result } : incompatible && error instanceof HttpError ? {
                 result: {
                     current_cli_version: CLI_VERSION,
                     current_api_contract_revision: API_CONTRACT_REVISION,
@@ -194,7 +211,7 @@ function reportCLIError(error, contract) {
                                     : providerRejected
                                         ? "告诉用户数据来源没有接受本次请求，但没有说明是输入错误，并按 result.quota 说明额度状态，然后停止。不要转述内部错误、修改输入、重试或创建新查询。"
                                         : capabilityInputInvalid
-                                            ? "告诉用户当前输入不完整或格式不正确；数据来源尚未调用，额度没有变化。不要转述技术错误或原样重试；用户提供修正信息后继续同一次服务。"
+                                            ? "Agent按当前合同模板修正字段和JSON层级，保留用户原始需求，继续同一次服务。不要让用户修技术输入，只有真实业务歧义才询问。"
                                             : transportError
                                                 ? contract?.initialization
                                                     ? "本轮初始化检查未完成；CLI 已结束有限的网络尝试，尚未确认后端或设备就绪。结束本轮，网络恢复后可重新检查；不要继续登录或业务操作。"
@@ -202,17 +219,18 @@ function reportCLIError(error, contract) {
                                                         ? "临时网络故障；CLI 已仅对可安全重放的操作完成有限自动重试，但仍未获得完整响应。按 recovery 查询同一资源的权威状态；不要创建替代 Checkout、Execution、Payment 或 Refund。"
                                                         : "网络在完整响应前中断；当前写操作没有安全重放合同，因此 CLI 未自动重试。按 recovery 查询权威状态；不要原样重放或创建替代 Checkout、Execution、Payment 或 Refund。"
                                                 : backendOverrideError
-                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或准确设置为 https://dev.itpay.ai。"
+                                                    ? "移除 ITPAY_BACKEND_URL 使用正式环境，或按当前测试目标准确设置为 https://sandbox.itpay.ai 或 https://dev.itpay.ai。不要通过切换环境规避当前错误。"
                                                     : commandError?.instruction ?? authorizationInstruction ?? contract?.instruction ?? "检查命令参数后重试。",
             next: null,
+            ...(commandError?.interaction ? { interaction: commandError.interaction } : {}),
             recovery: incompatible || (transportError && contract?.initialization)
                 ? []
                 : backendInternal || providerConnectionUnavailable || providerTemporary || providerInputRejected || providerContractMismatch || providerRejected || capabilityInputInvalid
                     ? []
-                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
+                    : backendOverrideError ? [] : commandError?.recovery ?? (stateError ? stateRecovery : lockError ? lockRecovery : deviceError ? deviceRecovery : identityRecovery ? httpRecovery : contract?.recovery ?? []),
         }, {
-            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError ? { jsonOutput: process.argv.includes("--json") } : {}),
-            output: (text) => { process.stderr.write(text); },
+            ...(contract?.jsonOutput !== undefined ? { jsonOutput: contract.jsonOutput } : backendOverrideError || lockError || stateError ? { jsonOutput: process.argv.includes("--json") } : {}),
+            output: (text) => { process.stdout.write(text); },
         });
         process.exitCode = 1;
         return;
@@ -279,31 +297,56 @@ program
         });
     }
 });
+const authCmd = program.command("auth").description("Log in and bind this enrolled Agent to your ItPay account");
+for (const action of ["login", "status"]) {
+    authCmd.command(action).option("--json", "output JSON").action(async (options) => {
+        const config = loadConfig();
+        try {
+            const result = await agentAuth(action, config.baseURL, newBackendClient(config));
+            // AUTH06: auth output goes through the same envelope renderer as every
+            // other command — next/recovery keep Agent Type + Backend qualification
+            // and non-JSON output is human-readable instead of a raw JSON dump.
+            const envelope = {
+                status: String(result.status ?? "error"),
+                result: (result.result ?? Object.fromEntries(Object.entries(result).filter(([key]) => !["status", "instruction", "next", "recovery", "handoff"].includes(key)))),
+                ...(result.handoff ? { handoff: result.handoff } : {}),
+                instruction: typeof result.instruction === "string" ? result.instruction : "按返回状态继续。",
+                next: (result.next ?? null),
+                recovery: (result.recovery ?? []),
+            };
+            writeCommandEnvelope(envelope, { jsonOutput: Boolean(options.json) });
+            if (envelope.status === "auth_status_unknown")
+                process.exitCode = 1;
+        }
+        catch (error) {
+            reportCLIError(error, { jsonOutput: Boolean(options.json), code: "account_login_failed", initialization: true, instruction: "本轮授权检查未完成；保留设备及已有授权状态，按明确错误原因恢复。不要自动发起新的登录。" });
+        }
+    });
+}
 // --- device ---------------------------------------------------------------
 const deviceCmd = program.command("device").description("Recover the current official Backend registration after an operator-confirmed reset");
-deviceCmd.command("status")
-    .description("Verify this device with the current Backend; account binding is not queried")
+deviceCmd
+    .command("repair-lock")
+    .description("Safely inspect and recover a local Device identity lock left by an exited process")
     .option("--json", "output JSON instead of terminal text")
-    .action(async (options) => {
-    const config = loadConfig();
+    .action((options) => {
     try {
-        await requirePlatformCompatibility(newBackendClient(config));
-        const authority = new DeviceAuthority({
+        const config = loadConfig();
+        const status = new DeviceAuthority({
             baseURL: config.baseURL,
             ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
-            compatibilityHeaders: { "X-ItPay-CLI-Version": CLI_VERSION, "X-ItPay-Contract-Revision": API_CONTRACT_REVISION },
-        });
-        const verified = await authority.status();
+            compatibilityHeaders: {},
+        }).repairLock();
         writeCommandEnvelope({
-            status: "device_ready",
-            result: { ...verified, backend_url: config.baseURL, account_binding: "unavailable" },
-            instruction: "当前 Backend 已验证设备身份。此版本不查询账号绑定，不能据此认定已登录或未登录；无需在安装阶段登录，不自动开始业务。首次检查可登记设备，后续复用同一身份。",
+            status: status === "recovered" ? "device_lock_recovered" : status === "active" ? "device_lock_active" : "device_lock_absent",
+            result: { lock_status: status, device_identity_preserved: true },
+            instruction: status === "active" ? "本地锁占用或安全转换未完成；保留原身份，核对持有者及宿主现场后继续原任务。" : "本地锁无需进一步处理；继续原任务。",
             next: null,
             recovery: [],
-        }, { jsonOutput: Boolean(options.json) });
+        }, { jsonOutput: Boolean(options.json), plainResult: [`lock: ${status}`, "device_identity: preserved"] });
     }
     catch (error) {
-        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "device_status_unavailable", initialization: true, instruction: "本轮设备检查未完成；停止本轮，保留原身份，不自动发起登录。" });
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "device_lock_repair_failed", instruction: "本地锁无法安全检查；保留设备身份并联系维护者。" });
     }
 });
 deviceCmd
@@ -358,6 +401,56 @@ deviceCmd
         });
     }
 });
+deviceCmd
+    .command("reset-key")
+    .description("Discard the local Ed25519 device key and all Backend registrations so the next command enrolls as a new device")
+    .option("--confirm-key-reset", "confirm that the current device key must be abandoned and a new identity created")
+    .option("--json", "output JSON instead of terminal text")
+    .action(async (options) => {
+    const config = loadConfig();
+    try {
+        if (!config.agentType || !INSTALL_AGENT_TYPES.some(type => type === config.agentType)) {
+            throw new CommandContractError("agent_type_required", "supported Agent Type required before key reset", "先按真实宿主配置正式支持的Agent Type；尚未修改本地密钥。", [{ command: "itpay install --json", reason: "读取当前宿主配置" }]);
+        }
+        if (!options.confirmKeyReset) {
+            throw new CommandContractError("key_reset_confirmation_required", "--confirm-key-reset is required", "仅在用户或运营明确决定放弃旧身份后使用；会丢弃本地私钥，旧执行访问不会迁移。internal_error 需服务端恢复，不能换钥。", [{ command: "itpay docs show identity-and-sessions --json", reason: "检查适用边界" }]);
+        }
+        const reset = await new DeviceAuthority({
+            baseURL: config.baseURL,
+            ...(config.agentType ? { requestedAgentType: config.agentType } : {}),
+            compatibilityHeaders: {},
+        }).resetDeviceKey();
+        writeCommandEnvelope({
+            status: "device_key_reset",
+            result: {
+                removed_backend_registrations: reset.removedBackends,
+                private_key_preserved: false,
+                server_side_device: "orphaned_under_previous_key",
+            },
+            instruction: "本地设备私钥已重置；下一次需要设备身份的命令会以全新 Ed25519 密钥重新登记；这不能恢复旧身份的订单或用于刷新额度。服务端旧设备记录保留为孤儿；如需清理请走运营流程。",
+            next: {
+                command: `itpay --agent-type ${config.agentType} services list --limit 1 --json`,
+                reason: "用无业务写入的签名请求完成新密钥的重新登记",
+            },
+            recovery: [],
+        }, {
+            jsonOutput: Boolean(options.json),
+            plainResult: [
+                `removed_backend_registrations: ${reset.removedBackends.join(", ") || "none"}`,
+                "private_key: rotated (previous key discarded)",
+                "server_side_device: orphaned under previous key",
+            ],
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "device_key_reset_failed",
+            instruction: "仅在确认要放弃当前设备私钥时使用；普通 session 失效或 revoked 不需要本命令。",
+            recovery: [{ command: "itpay docs show identity-and-sessions --json", reason: "检查 Device 恢复边界" }],
+        });
+    }
+});
 // --- skill ----------------------------------------------------------------
 const skillCmd = program.command("skill").description("Read complete packaged Agent skills");
 skillCmd
@@ -832,6 +925,13 @@ program
     .option("--id <checkout_id>")
     .option("--token <display_token>")
     .option("--locale <locale>", "payment card language: zh-CN|en", "zh-CN")
+    .option("--present <method>", "display once: auto|browser|image|link|none (JSON default plans only)")
+    .option("--no-open", "never open a browser window")
+    .option("--viewer <viewer>", "device the human is looking at: desktop|mobile|unknown")
+    .option("--relay-option <ref>", "server-issued contact option reference for message relay")
+    .option("--confirm-relay", "confirm the human explicitly consented to this relay send")
+    .option("--request-key <key>", "stable idempotency key for a relay request")
+    .option("--relay-status <relay_id>", "read a prior relay result; never resends")
     .option("--json", "output compact JSON")
     .action(async (options) => {
     const config = loadConfig();
@@ -849,12 +949,22 @@ program
         await runCheckoutPresentation(backend, {
             checkoutID,
             displayToken,
+            ...(snap.lastCheckoutID === checkoutID && snap.lastCheckoutURL
+                ? { savedCheckoutURL: snap.lastCheckoutURL }
+                : {}),
             host,
             ...(options.target ? { target: options.target } : {}),
             ...(config.agentType ? { agentType: config.agentType } : {}),
             baseURL: config.baseURL,
             locale: options.locale,
             jsonOutput: Boolean(options.json),
+            ...(options.present ? { present: options.present } : {}),
+            ...(options.noOpen ? { noOpen: true } : {}),
+            ...(options.viewer ? { viewer: options.viewer } : {}),
+            ...(options.relayOption ? { relayOption: options.relayOption } : {}),
+            ...(options.confirmRelay ? { confirmRelay: true } : {}),
+            ...(options.requestKey ? { requestKey: options.requestKey } : {}),
+            ...(options.relayStatus ? { relayStatus: options.relayStatus } : {}),
         });
     }
     catch (error) {
@@ -1022,6 +1132,49 @@ feedback
         });
     }
 });
+const aftercare = program.command("aftercare").description("Railway manual refund/change requests; never automatic supplier operations");
+aftercare.command("list").requiredOption("--order <order_id>").option("--json").action(async (options) => {
+    try {
+        const config = loadConfig();
+        writeCommandEnvelope(await runAftercareList(newBackendClient(config), options.order), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_read_failed", instruction: "核对原订单与当前身份；铁路人工售后不改变平台内容授权，不换身份绕过。", recovery: [{ command: "itpay services list --json", reason: "找回当前身份原订单" }] });
+    }
+});
+aftercare.command("create").requiredOption("--order <order_id>").requiredOption("--input-json <file>").option("--json").action(async (options) => {
+    const recovery = [{ command: `itpay aftercare list --order ${options.order} --json`, reason: "读取原订单当前行程与完整申请模板" }];
+    try {
+        const config = loadConfig();
+        const input = readInputJsonObject(options.inputJson, "rail_aftercare_input_invalid", recovery);
+        writeCommandEnvelope(await runAftercareCreate(newBackendClient(config), config, options.order, input), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_create_failed", instruction: "保留原申请与用户范围，按实际错误读取当前模板或办理状态；不猜金额/身份，不重复未知操作。", recovery });
+    }
+});
+aftercare.command("get").argument("<case_id>").option("--json").action(async (id, options) => {
+    try {
+        const config = loadConfig();
+        writeCommandEnvelope(await runAftercareGet(newBackendClient(config), id), { jsonOutput: Boolean(options.json) });
+    }
+    catch (error) {
+        reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_read_failed", instruction: "核对当前身份的原申请，不换身份或探测其他申请。", recovery: [] });
+    }
+});
+for (const action of ["respond", "cancel"]) {
+    aftercare.command(action).argument("<case_id>").requiredOption("--input-json <file>").option("--json").action(async (id, options) => {
+        const recovery = [{ command: `itpay aftercare get ${id} --json`, reason: "读取原申请当前版本与明确下一步" }];
+        try {
+            const config = loadConfig();
+            const input = readInputJsonObject(options.inputJson, "rail_aftercare_input_invalid", recovery);
+            writeCommandEnvelope(await runAftercareRespond(newBackendClient(config), id, input, action === "cancel"), { jsonOutput: Boolean(options.json) });
+        }
+        catch (error) {
+            reportCLIError(error, { jsonOutput: Boolean(options.json), code: "aftercare_response_failed", instruction: "按原申请当前版本处理；取消不撤回供应商操作，未知资金不重试。", recovery });
+        }
+    });
+}
 const refund = program
     .command("refund")
     .enablePositionalOptions()
@@ -1092,7 +1245,7 @@ refund.command("get").argument("<refund_request_id>").option("--json", "output J
         });
     }
 });
-refund.command("watch").argument("<refund_request_id>").option("--interval <seconds>", "poll interval", Number, 2).option("--timeout <seconds>", "timeout", Number, 120).option("--json", "output JSON instead of terminal text").action(async (id, options) => {
+refund.command("watch").argument("<refund_request_id>").option("--interval <seconds>", "poll interval", Number, 2).option("--timeout <seconds>", "bounded wait; returns on change/manual attention", Number, 20).option("--json", "output JSON instead of terminal text").action(async (id, options) => {
     const config = loadConfig();
     try {
         await runWatchRefund(newBackendClient(config), id, {
@@ -1230,7 +1383,114 @@ vault
     }
 });
 // --- service execution ----------------------------------------------------
+const WORKFLOW_INPUT_JSON_MAX_BYTES = 256 * 1024;
+function readInputJsonObject(file, code, recovery) {
+    let parsed;
+    try {
+        if (statWorkflowInputFile(file).size > WORKFLOW_INPUT_JSON_MAX_BYTES) {
+            throw new CommandContractError(code, `--input-json file exceeds ${WORKFLOW_INPUT_JSON_MAX_BYTES} bytes`, "输入文件过大；只提交服务端 input_schema 声明的字段。", recovery);
+        }
+        parsed = JSON.parse(readWorkflowInputFile(file, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof CommandContractError)
+            throw error;
+        throw new CommandContractError(code, `--input-json is not readable valid JSON: ${error instanceof Error ? error.message : String(error)}`, "确认文件存在且为合法 JSON；按服务端 input_schema 字段填写。", recovery);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CommandContractError(code, "--input-json must contain a JSON object", "确认输入必须是 JSON 对象；按服务端 input_schema 字段填写。", recovery);
+    }
+    return parsed;
+}
 const services = program.command("services").description("Generic V3 Service Execution commands");
+services
+    .command("run")
+    .description("Run a declared service operation; preparation approval is required before Checkout")
+    .option("--operation <operation_id>", "operation declared by the public service definition")
+    .argument("<service_id>")
+    .option("--input-json <file>", "JSON object containing the service input")
+    .option("--execution <execution_id>", "resume the same execution")
+    .option("--timeout <seconds>", "maximum wait before returning current progress", Number, 120)
+    .option("--host <host>")
+    .option("--target <target>")
+    .option("--json", "output JSON")
+    .action(async (serviceID, options) => {
+    const config = loadConfig();
+    try {
+        let input = options.inputJson
+            ? readInputJsonObject(options.inputJson, "workflow_input_invalid", [
+                { command: `itpay services run ${serviceID} --json`, reason: "重新读取服务输入声明" },
+            ])
+            : undefined;
+        let continuation;
+        if (options.operation && input !== undefined) {
+            const parameters = input.input;
+            if (typeof parameters !== "object" || parameters === null || Array.isArray(parameters))
+                throw new CommandContractError("operation_input_invalid", "operation JSON must include an input object", "使用公开操作返回的完整JSON模板，顶层input是业务输入；保留服务端continuation。", []);
+            const reference = input.continuation;
+            if (reference !== undefined) {
+                if (typeof reference !== "object" || reference === null || Array.isArray(reference) || !("service_execution_id" in reference) || !("snapshot_id" in reference) || typeof reference.service_execution_id !== "string" || typeof reference.snapshot_id !== "string")
+                    throw new CommandContractError("operation_input_invalid", "invalid continuation reference", "保留结果详情返回的continuation，不猜执行或snapshot。", []);
+                continuation = { service_execution_id: reference.service_execution_id, snapshot_id: reference.snapshot_id };
+            }
+            input = Object.fromEntries(Object.entries(parameters));
+        }
+        if (!Number.isFinite(options.timeout) || options.timeout < 0 || options.timeout > 600) {
+            throw new Error("timeout must be between 0 and 600 seconds");
+        }
+        await runServicesRun(newBackendClient(config), config, serviceID, input, {
+            ...(options.execution ? { executionID: options.execution } : {}),
+            ...(options.operation ? { operationID: options.operation } : {}),
+            ...(continuation ? { continuation } : {}),
+            jsonOutput: Boolean(options.json),
+            host: withHost(options.host, config.agentType, options.target),
+            ...(options.target ? { target: options.target } : {}),
+            timeoutSeconds: options.timeout,
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json), code: "workflow_run_failed",
+            instruction: "本次操作失败；按已返回的具体原因和恢复动作处理。没有恢复动作时停止，不猜字段或重复创建购买。", recovery: [],
+        });
+    }
+});
+services
+    .command("page")
+    .description("Read one page of a saved service result set (same stored version, no re-query, no quota)")
+    .argument("<service_execution_id>")
+    .argument("<result_item_id>")
+    .option("--offset <offset>", "zero-based candidate offset", Number, 0)
+    .option("--cursor <cursor>", "opaque v2 page cursor (rcur_<offset>); takes precedence over --offset")
+    .option("--limit <limit>", "page size (1-20)", Number, 20)
+    .option("--json", "output JSON")
+    .action(async (serviceExecutionID, resultItemID, options) => {
+    const config = loadConfig();
+    const backend = newBackendClient(config);
+    try {
+        const cursorOffset = typeof options.cursor === "string" && /^rcur_\d+$/.test(options.cursor)
+            ? Number(options.cursor.slice(5))
+            : undefined;
+        if (options.cursor !== undefined && cursorOffset === undefined) {
+            throw new CommandContractError("cursor_invalid", "--cursor must be an opaque rcur_<offset> token from a previous page response", "--cursor 需为上一页返回的 rcur_<offset> 不透明游标。", []);
+        }
+        await runServicesPage(backend, serviceExecutionID, resultItemID, {
+            offset: cursorOffset ?? options.offset,
+            limit: options.limit,
+            jsonOutput: Boolean(options.json),
+        });
+    }
+    catch (error) {
+        reportCLIError(error, {
+            jsonOutput: Boolean(options.json),
+            code: "service_page_failed",
+            instruction: "分页读取的是已保存的同版本结果；不要重新发起查询或新建 execution。",
+            recovery: [
+                { command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前结果页与合法动作" },
+            ],
+        });
+    }
+});
 services
     .command("start")
     .description("Start a contract-backed service execution")
@@ -1266,12 +1526,18 @@ services
     .argument("<service_execution_id>")
     .requiredOption("--capability <capability_id>")
     .option("--input <key=value>", "redacted input summary", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the complete capability input")
     .option("--json", "output JSON")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, parseKeyValueList(options.input), { jsonOutput: Boolean(options.json) });
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("capability_input_invalid", "--input and --input-json cannot be combined", "嵌套输入用 --input-json <file>，扁平输入用 --input key=value，二选一；本次未调用供应商。", recovery);
+        }
+        const input = options.inputJson ? readInputJsonObject(options.inputJson, "capability_input_invalid", recovery) : parseKeyValueList(options.input);
+        await runServicesInvoke(backend, config, serviceExecutionID, options.capability, input, { jsonOutput: Boolean(options.json) });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1297,12 +1563,18 @@ services
     .option("--result-item <service_capability_result_item_id>")
     .option("--required-before <step>")
     .option("--input <key=value>", "action input snapshot", collectOption, [])
+    .option("--input-json <file>", "JSON object containing the full action input snapshot")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesAction(backend, serviceExecutionID, options.action, parseKeyValueList(options.input), {
+        const recovery = [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前动作要求" }];
+        if (options.inputJson && options.input.length > 0) {
+            throw new CommandContractError("service_action_invalid", "--input and --input-json cannot be combined", "--input 与 --input-json 只能二选一：嵌套结构用 --input-json <file>，扁平键值用 --input key=value。", recovery);
+        }
+        const fileInput = options.inputJson ? readInputJsonObject(options.inputJson, "service_action_invalid", recovery) : {};
+        await runServicesAction(backend, serviceExecutionID, options.action, { ...fileInput, ...parseKeyValueList(options.input) }, {
             ...(options.actorType ? { actorType: options.actorType } : {}),
             ...(options.actorId ? { actorID: options.actorId } : {}),
             ...(options.status ? { status: options.status } : {}),
@@ -1447,12 +1719,17 @@ services
     .command("next")
     .description("Show the next recommended agent action for a Service Execution")
     .argument("<service_execution_id>")
+    .option("--since-snapshot <snapshot_id>", "delta read: suppress the journey payload when unchanged")
+    .option("--timeout <seconds>", "wait up to 120 seconds for a useful result on this execution", (value) => Number(value))
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json) });
+        if (options.timeout !== undefined && (!Number.isInteger(options.timeout) || options.timeout < 0 || options.timeout > 120)) {
+            throw new Error("--timeout must be an integer from 0 to 120");
+        }
+        await runServicesNext(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), sinceSnapshot: options.sinceSnapshot, timeoutSeconds: options.timeout });
     }
     catch (error) {
         reportCLIError(error, {
@@ -1465,20 +1742,28 @@ services
 });
 services
     .command("read-result")
-    .description("Read a human-granted service result for this agent")
+    .description("Read saved railway results or human-granted service content")
     .argument("<service_execution_id>")
+    .option("--snapshot <snapshot_id>", "Smart: saved snapshot catalog; add --journey for a journey detail. Exact: saved station-pair rows without --snapshot")
+    .option("--journey <journey_id>", "rail.progressive.v2: journey id to read")
+    .option("--offset <offset>", "saved journey offset", Number, 0)
+    .option("--limit <limit>", "rows per page (1-20): Exact 20, Smart 3", Number)
+    .option("--all", "read every saved journey page")
     .option("--json", "output JSON instead of terminal text")
     .action(async (serviceExecutionID, options) => {
     const config = loadConfig();
     const backend = newBackendClient(config);
     try {
-        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json) });
+        await runServicesReadResult(backend, serviceExecutionID, { jsonOutput: Boolean(options.json), snapshot: options.snapshot, journey: options.journey,
+            offset: options.offset, limit: options.limit, all: Boolean(options.all) });
     }
     catch (error) {
         reportCLIError(error, {
             jsonOutput: Boolean(options.json),
-            code: "agent_access_denied",
-            instruction: "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。",
+            code: error instanceof HttpError && error.code === "agent_access_denied" ? "agent_access_denied" : "service_result_read_failed",
+            instruction: error instanceof HttpError && error.code === "agent_access_denied"
+                ? "请用户在订单页面重新授权；不要使用开发者权限绕过授权或退款锁。"
+                : "读取同一服务的已保存结果；若快照已不可读，先查看该服务当前状态和有效动作。",
             recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "检查交付模式和 grant 状态" }],
         });
     }
@@ -1512,6 +1797,7 @@ services
         });
     }
 });
+registerSell(program);
 program.parseAsync(process.argv).catch((error) => {
     reportCLIError(error);
 });

package/dist/src/render/browser.js

@@ -0,0 +1,65 @@
+// Local browser dispatch for `--present browser`. Opens the URL via the OS
+// opener with an argv array — never a model-generated shell string. Dispatch
+// proves only that the request was accepted by the OS; it never means the
+// page became visible (that would be `page_loaded`, which needs evidence).
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+// Official HTTPS origins (or the loopback dev origin behind ITPAY_CLI_DEV).
+// No userinfo, no non-http(s) schemes, no redirect chains — the opener gets
+// exactly this URL once.
+export function isPresentableURL(raw, baseURL, env = process.env) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password)
+        return false;
+    if (env.ITPAY_CLI_DEV === "1" && /^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(url.origin))
+        return true;
+    if (url.protocol !== "https:")
+        return false;
+    const allowedOrigins = new Set(["https://app.itpay.ai", "https://sandbox.itpay.ai", "https://dev.itpay.ai"]);
+    if (baseURL) {
+        try {
+            allowedOrigins.add(new URL(baseURL).origin);
+        }
+        catch {
+            /* ignore malformed base URL */
+        }
+    }
+    return allowedOrigins.has(url.origin);
+}
+export function openInSystemBrowser(raw, baseURL, env = process.env) {
+    if (!isPresentableURL(raw, baseURL, env)) {
+        return Promise.resolve({ status: "failed", reason: "url_rejected" });
+    }
+    const [command, args] = openerArgv(raw);
+    if (!command) {
+        return Promise.resolve({ status: "unavailable", reason: "no system opener on this platform" });
+    }
+    return new Promise((resolvePromise) => {
+        const child = spawn(command, args, { detached: true, stdio: "ignore" });
+        child.once("error", (error) => resolvePromise({ status: "failed", reason: error.message }));
+        child.once("spawn", () => {
+            child.unref();
+            resolvePromise({ status: "dispatch_accepted", argv: [command, ...args] });
+        });
+    });
+}
+function openerArgv(url) {
+    switch (platform()) {
+        case "darwin":
+            return ["open", [url]];
+        case "win32":
+            return ["cmd.exe", ["/c", "start", "", url]];
+        case "linux":
+        case "freebsd":
+        case "openbsd":
+            return ["xdg-open", [url]];
+        default:
+            return [undefined, []];
+    }
+}