@itpay/cli 2.0.38 → 2.0.39

package/README.md

@@ -128,3 +128,9 @@ Source boundaries:
 - `src/state`: local Device Authority, idempotency journal, and recovery handles.
 - `docs/cli-reference`: normative command contracts.
 - `docs/agent/buyer`: packaged progressive workflow guidance.
+
+### Run a published service
+
+Use `itpay services run <service_id> --input-json ./input.json --json` for a published workflow. The input file must contain a JSON object matching the service input schema. With no input file, the CLI reports required fields and a command to continue the same execution.
+
+Use `itpay services run <service_id> --execution <execution_id> --json` to resume. At payment, the CLI uses the existing Checkout QR/card handoff. The backend continues after verified payment even if the CLI exits. `--timeout <seconds>` controls initial status polling (default 120, maximum 600). Use existing order/refund commands for refund requests; an application is not a successful refund until its final status confirms success.

package/dist/src/client/backend.js

@@ -108,6 +108,9 @@ export class BackendClient {
     startServiceExecution(input) {
         return this.http.post("/v1/service-executions", input);
     }
+    advanceServiceExecution(id, input, idempotencyKey) {
+        return this.http.post(`/v1/service-executions/${encodeURIComponent(id)}/advance`, { input, idempotency_key: idempotencyKey });
+    }
     invokeServiceCapability(serviceExecutionID, capabilityID, input) {
         return this.http.post(`/v1/service-executions/${encodeURIComponent(serviceExecutionID)}/capabilities/${encodeURIComponent(capabilityID)}/invoke`, input, { replaySafe: Boolean(input.idempotency_key) });
     }

package/dist/src/commands/catalog.js

@@ -25,6 +25,7 @@ export async function runCatalogList(backend, options = {}) {
 }
 function summarizeService(item) {
     const flow = item.service_flow;
+    const offer = item.variants?.[0];
     return {
         service_id: item.service_id ?? null,
         title: item.title,
@@ -43,6 +44,12 @@ function summarizeService(item) {
                 description: flow.primary_service.description,
                 price: formatProductMoney(flow.primary_service.amount_minor, flow.primary_service.currency),
             },
+        } : offer ? {
+            primary_offer: {
+                title: offer.title || item.title,
+                description: item.description ?? "",
+                price: formatProductMoney(offer.amount_minor, offer.currency),
+            },
         } : {}),
     };
 }

package/dist/src/commands/services.js

@@ -1,3 +1,5 @@
+import { HttpError } from "../client/http.js";
+import { HttpTransportError } from "../client/transport.js";
 import { operationID } from "../state/config.js";
 import { validateContext } from "../state/client_context.js";
 import { dispatchRender } from "../render/index.js";
@@ -20,6 +22,10 @@ export async function runServicesStart(backend, serviceID, options = {}) {
             ...(options.clientContext ?? {}),
         },
     });
+    if (response.workflow_entry) {
+        writeCommandEnvelope({ status: "input_required", result: { service_execution_id: response.execution.service_execution_id, service_id: serviceID, input_schema: response.workflow_entry.input_schema }, instruction: "根据服务声明填写输入，然后继续同一服务执行。", next: { command: `itpay services run ${serviceID} --execution ${response.execution.service_execution_id} --input-json <file> --json`, reason: "提交买家输入" }, recovery: [] }, { ...options });
+        return;
+    }
     const capability = response.capabilities.find((item) => item.phase === response.execution.phase && !item.requires_payment);
     const requiredInput = requiredInputFields(capability?.input_schema);
     const command = capability
@@ -384,6 +390,10 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         ...(options.deliveryContact ?? {}),
         ...(options.email ? { email: options.email } : {}),
     };
+    if (!options.resume && !capabilityID) {
+        const model = await backend.getServiceExecution(serviceExecutionID);
+        capabilityID = model.workflow_entry?.capability_id;
+    }
     if (!options.resume && !capabilityID) {
         throw new CommandContractError("capability_required", "--capability is required when creating a service checkout", "使用当前 Service Execution 返回的付费 capability；恢复已有 Checkout 时改用 --resume。", [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取当前允许的付费 capability" }]);
     }
@@ -395,7 +405,7 @@ export async function runServicesCheckout(backend, config, serviceExecutionID, c
         }
         const lockedInput = options.lockedInput ?? {};
         const missingInput = missingRequiredInput(capability.input_schema, lockedInput);
-        if (missingInput.length > 0 && readModel.execution.next_action !== "create_checkout") {
+        if (missingInput.length > 0 && !readModel.workflow_entry && readModel.execution.next_action !== "create_checkout") {
             throw new CommandContractError("capability_input_invalid", `missing required capability input: ${missingInput.join(", ")}`, "补齐付费 capability 的 required_input；本次没有创建 quote、Checkout 或订单。", [{ command: checkoutCommand(serviceExecutionID, capability, lockedInput), reason: "提交完整且会被锁定的服务输入" }]);
         }
         if (capability.delivery_email_required && String(deliveryContact.email ?? "").trim() === "") {
@@ -642,6 +652,32 @@ function servicesNextEnvelope(model) {
     const execution = model.execution;
     const currentDelivery = model.current_delivery ?? model.delivery_bindings.at(-1);
     const lockedRefund = model.refunds.find((refund) => refund.access_locked);
+    if (model.workflow_entry && !lockedRefund && !["completed", "delivery"].includes(model.workflow?.status ?? "")) {
+        const id = execution.service_execution_id;
+        const state = model.workflow?.status ?? "input_required";
+        const recovery = state === "recovery_required" || state === "failed";
+        let command = `itpay services next ${id} --json`;
+        if (state === "payment")
+            command = `itpay services checkout ${id} --json`;
+        if (state === "input_required")
+            command = `itpay services run ${execution.service_id} --execution ${id} --input-json <file> --json`;
+        return {
+            status: state,
+            result: {
+                service_execution_id: id,
+                service_id: execution.service_id,
+                workflow: model.workflow,
+                ...(state === "input_required" ? { input_schema: model.workflow_entry.input_schema } : {}),
+            },
+            instruction: recovery
+                ? "执行未完成，请按步骤错误处理；不要重建执行或重复调用。"
+                : state === "payment"
+                    ? "服务已到付款步骤，使用现有 Checkout 完成扫码付款。"
+                    : "继续读取同一执行；缺少输入时按服务声明补齐。",
+            next: recovery ? null : { command, reason: "继续当前流程" },
+            recovery: [],
+        };
+    }
     if (lockedRefund) {
         const terminal = lockedRefund.status === "succeeded";
         return {
@@ -1066,3 +1102,58 @@ function tokenizedCheckoutURL(checkoutURL, displayToken, qrPayload) {
         return `${checkoutURL}${separator}display_token=${encodeURIComponent(displayToken)}`;
     }
 }
+export async function runServicesRun(backend, config, serviceID, input, options = {}) {
+    let id = options.executionID;
+    try {
+        if (!id) {
+            const started = await backend.startServiceExecution({
+                service_id: serviceID,
+                client_context: { host: options.host ?? "terminal", ...(options.target ? { target: options.target } : {}) },
+            });
+            id = started.execution.service_execution_id;
+            if (!started.workflow_entry) {
+                await runServicesNext(backend, id, options);
+                return;
+            }
+        }
+        let model = await backend.getServiceExecution(id);
+        if (model.execution.service_id !== serviceID)
+            throw new Error("execution belongs to another service");
+        if (!model.workflow_entry || (input === undefined && !model.workflow)) {
+            await runServicesNext(backend, id, options);
+            return;
+        }
+        if (input !== undefined) {
+            model = await backend.advanceServiceExecution(id, input, `workflow-input:${id}`);
+        }
+        const until = Date.now() + (options.timeoutSeconds ?? 120) * 1000;
+        const sleep = options.sleep ?? ((milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)));
+        while (["queued", "running"].includes(model.workflow?.status ?? "") && Date.now() < until) {
+            await sleep(options.pollIntervalMS ?? 1500);
+            model = await backend.getServiceExecution(id);
+        }
+        if (model.refunds.some(refund => refund.access_locked)) {
+            await runServicesNext(backend, id, options);
+            return;
+        }
+        if (model.workflow?.status === "payment") {
+            await runServicesCheckout(backend, config, id, model.workflow_entry?.capability_id, {
+                ...options,
+                ...(config.agentType ? { agentType: config.agentType } : {}),
+                resume: model.checkout_bindings.length > 0,
+            });
+            return;
+        }
+        await runServicesNext(backend, id, options);
+    }
+    catch (cause) {
+        if (cause instanceof CommandContractError || cause instanceof HttpError)
+            throw cause;
+        if (cause instanceof HttpTransportError && !id) {
+            throw new CommandContractError("workflow_start_outcome_unknown", cause.message, "创建服务执行时没有收到完整响应。先查询当前身份可见的执行；不要直接重跑并创建替代执行。", [{ command: "itpay services list --json", reason: "查找可能已经创建的服务执行" }]);
+        }
+        if (cause instanceof HttpTransportError)
+            throw cause;
+        throw new CommandContractError("workflow_run_failed", cause instanceof Error ? cause.message : "workflow run failed", "保留当前执行并按错误处理，不要重复创建服务执行。", [{ command: `itpay services run ${serviceID} --execution ${id} --json`, reason: "恢复同一执行" }]);
+    }
+}

package/dist/src/main.js

@@ -1,3 +1,5 @@
+import { readFileSync as readWorkflowInputFile } 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.
@@ -1215,6 +1217,41 @@ vault
 });
 // --- service execution ----------------------------------------------------
 const services = program.command("services").description("Generic V3 Service Execution commands");
+services
+    .command("run")
+    .description("Run a published service and present Checkout when payment is required")
+    .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 {
+        const input = options.inputJson ? JSON.parse(readWorkflowInputFile(options.inputJson, "utf8")) : undefined;
+        if (input !== undefined && (!input || typeof input !== "object" || Array.isArray(input))) {
+            throw new Error("input JSON must be an object");
+        }
+        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 } : {}),
+            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: "按服务输入声明补齐参数；已有 execution 时继续该执行。", recovery: [],
+        });
+    }
+});
 services
     .command("start")
     .description("Start a contract-backed service execution")

package/dist/src/state/config.js

@@ -12,8 +12,8 @@ import { DeviceAuthority } from "./device_authority.js";
 import { OperationJournal } from "./operation_journal.js";
 export const DEFAULT_BASE_URL = "https://app.itpay.ai";
 export const SANDBOX_BASE_URL = "https://sandbox.itpay.ai";
-export const CLI_VERSION = "2.0.38";
-export const API_CONTRACT_REVISION = "sha256:06930cb6833e761813d6ad2e260cf0605469234b515402fa25c0c58b9f3c27e9";
+export const CLI_VERSION = "2.0.39";
+export const API_CONTRACT_REVISION = "sha256:1d637a77a49d5a821ef55f88bd9107427aede63f9652335b5d1a6a870a7e92a0";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

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

@@ -1,6 +1,6 @@
 # `itpay services`
 
-> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Seller-published workflows enter the same Buyer execution, Checkout, delivery, and refund state machine as ItPay services.
 
 ## 命令范围
 
@@ -22,6 +22,7 @@
 ## 子命令
 
 - [`start`](start.md)
+- [`run`](run.md)
 - [`invoke`](invoke.md)
 - [`action`](action.md)
 - [`quote`](quote.md)
@@ -40,7 +41,7 @@
 itpay services --help
 ```
 
-输出十个子命令及一句选择规则：正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
+输出十一个子命令及一句选择规则：运行已发布服务使用 `run`，正常推进使用 `next`，深度诊断才使用 `get/events`。未知子命令返回参数错误和本 help，不创建 Execution。
 
 ## Agent Type / Host
 

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

@@ -0,0 +1,74 @@
+# `itpay services run`
+
+## 范围与意义
+
+运行 Catalog 中已发布的通用 Buyer workflow。CLI 只提交服务声明要求的输入，并复用现有 Service Execution、Checkout、交付和退款命令；它不解释或执行 Seller 提供的任意命令文本。
+
+没有提供输入时，本命令创建一次 Execution，返回已发布的 JSON input schema，并要求 Agent 继续同一 Execution。已有 Execution 必须通过 `--execution` 恢复，不能创建替代 Execution。
+
+## 语法与参数
+
+```bash
+itpay services run <service_id>
+  [--input-json <file>]
+  [--execution <service_execution_id>]
+  [--timeout <seconds>]
+  [--host <host>]
+  [--target <target>]
+  [--json]
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| `service_id` | Catalog 返回的服务 ID。恢复时必须与 Execution 所属服务一致。 |
+| `--input-json` | UTF-8 JSON 文件；顶层必须是 object，并符合服务发布的 input schema。 |
+| `--execution` | 恢复同一 Execution。不得用它切换服务或绕过原状态。 |
+| `--timeout` | 本次等待 workflow 状态变化的秒数，默认 120，范围 0–600；超时只返回当前状态。 |
+| `--host` / `--target` | Host 展示上下文，不是业务输入或 Buyer 身份。 |
+| `--json` | 输出稳定 JSON 信封。 |
+
+## 缺少输入
+
+```json
+{
+  "status": "input_required",
+  "result": {
+    "service_execution_id": "<execution_id>",
+    "service_id": "<service_id>",
+    "input_schema": { "type": "object", "required": ["<field>"] }
+  },
+  "instruction": "根据服务声明填写输入，然后继续同一服务执行。",
+  "next": {
+    "command": "itpay services run <service_id> --execution <execution_id> --input-json <file> --json",
+    "reason": "提交买家输入"
+  },
+  "recovery": []
+}
+```
+
+Agent 必须展示 schema 所需信息并等待用户提供真实输入；不得猜值，也不得为补输入创建新 Execution。
+
+## 执行与付款
+
+提供输入后，CLI 使用稳定 idempotency key 向同一 Execution 提交一次。`queued` 或 `running` 只轮询该 Execution。进入付款步骤时，CLI 调用现有 `services checkout`，返回其标准 `human_checkout_required` 输出和 Host handoff；不会实现第二套付款逻辑。
+
+付款完成后即使 CLI 已退出，Backend 仍继续该 workflow。再次运行：
+
+```bash
+itpay services run <service_id> --execution <execution_id> --json
+```
+
+只恢复当前状态。交付、Vault 授权和退款继续使用 `services next`、`services read-result`、`vault` 与 `refund` 的既有合同。
+
+## 终态和异常
+
+- 成功、付款、交付、授权、退款锁等状态使用既有命令的标准信封，不额外包装 Seller 专用格式。
+- 既有 Checkout、身份、兼容性和网络错误保持原错误码、instruction 与 recovery；`services run` 不得覆盖可执行的邮箱、登录、升级或状态恢复指令。
+- 如果创建 Execution 后未收到完整响应，返回 `workflow_start_outcome_unknown`，只允许先执行 `itpay services list --json` 查找刚创建的 Execution；不得直接重跑 `services run` 创建替代 Execution。
+- `recovery_required` 或 `failed` 返回当前 workflow step，`next: null`，并明确禁止重建 Execution 或重放结果未知的 Provider 请求。
+- service 不匹配、输入文件不是 JSON object、timeout 越界或 Backend 错误返回 `workflow_run_failed`。
+- `--timeout` 到期不是失败，只返回同一 Execution 当前可恢复状态。
+
+## Agent Type / Host
+
+所有 Local Agent Type 共享同一状态机和 JSON 事实。Host 只改变付款链接、二维码或附件的展示方式，不改变身份、价格、workflow 或交付权限。

package/docs/cli-reference/index.md

@@ -78,6 +78,7 @@ Commander 自动提供的 `itpay help [command]` 与 `itpay <group> help [subcom
 ### 通用服务执行
 
 - [`itpay services`](commands/services/index.md)
+  - [`itpay services run`](commands/services/run.md)
   - [`itpay services start`](commands/services/start.md)
   - [`itpay services invoke`](commands/services/invoke.md)
   - [`itpay services action`](commands/services/action.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itpay/cli",
-  "version": "2.0.38",
+  "version": "2.0.39",
   "description": "The ItPay CLI for services, orders, and human-authorized purchased content.",
   "type": "module",
   "bin": {