@itpay/cli 2.1.34 → 2.1.40

package/dist/src/commands/rail_catalog.js

@@ -1,261 +1 @@
-import { CLI_VERSION, cliDistribution } from "../state/config.js";
-export class RailCatalogEncodingError extends Error {
-    constructor(encoding) {
-        super(`catalog encoding ${JSON.stringify(encoding)} is not supported by CLI ${CLI_VERSION} ` +
-            `(${cliDistribution()}); obtain a compatible exact version through this installation channel. ` +
-            `The committed catalog is intact`);
-        this.name = "rail_catalog_encoding";
-    }
-}
-function scopeFromProfiles(value) {
-    const profiles = Array.isArray(value) ? value : [];
-    const selected = profiles.find((p) => Array.isArray(p) && Array.isArray(p[1]) && p[1].includes("balanced")) ?? profiles[0];
-    if (!Array.isArray(selected))
-        return { origin: "legacy_unknown", destination: "legacy_unknown",
-            duration_basis: "legacy_unknown", arrival_basis: "legacy_unknown", cost_basis: "legacy_unknown",
-            duration_minutes: null, estimated_total_cost: null, cost_incomplete: true };
-    const extras = selected[10] && typeof selected[10] === "object" ? selected[10] : {};
-    const total = typeof selected[9] === "number" && extras.ci !== true ? selected[9] / 100 : null;
-    return {
-        origin: extras.os ?? "legacy_unknown", destination: extras.ds ?? "legacy_unknown",
-        duration_basis: extras.db ?? "legacy_unknown", arrival_basis: extras.ab ?? "legacy_unknown",
-        cost_basis: extras.cb ?? "legacy_unknown", duration_minutes: selected[8] ?? null,
-        estimated_total_cost: total, cost_incomplete: extras.ci === true,
-    };
-}
-function asString(v) {
-    return typeof v === "string" && v.length > 0 ? v : undefined;
-}
-function asIndex(v, bound) {
-    if (typeof v !== "number" || !Number.isInteger(v) || v < 0 || v >= bound) {
-        throw new Error("shared_rows: index out of bounds");
-    }
-    return v;
-}
-function asObject(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
-function datedTime(date, value) {
-    const raw = asString(value);
-    if (!raw)
-        return null;
-    if (/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}/.test(raw))
-        return raw.replace("T", " ").slice(0, 16);
-    const short = raw.match(/^(\d{2}:\d{2})(?:\+(\d+))?$/);
-    const day = asString(date);
-    if (!short || !day)
-        return null;
-    if (!short[2])
-        return `${day} ${short[1]}`;
-    const shifted = new Date(`${day}T00:00:00Z`);
-    if (Number.isNaN(shifted.getTime()))
-        return null;
-    shifted.setUTCDate(shifted.getUTCDate() + Number(short[2]));
-    return `${shifted.toISOString().slice(0, 10)} ${short[1]}`;
-}
-function elapsedMinutes(departure, arrival) {
-    if (!departure || !arrival)
-        return null;
-    const start = Date.parse(departure.replace(" ", "T") + "Z");
-    const end = Date.parse(arrival.replace(" ", "T") + "Z");
-    return Number.isFinite(start) && Number.isFinite(end) && end >= start ? (end - start) / 60_000 : null;
-}
-function seatOffer(row, names) {
-    if (!Array.isArray(row))
-        return null;
-    const extras = asObject(row[7]);
-    const code = asString(row[1]);
-    return {
-        offer_ref: row[0], seat_type: code ?? null, seat_name: code ? names[code] ?? code : null,
-        inventory_status: row[2] ?? null, quantity: row[3] ?? null, unit_price_fen: row[4] ?? null,
-        eligible: row[5] === true, requires_quote: row[6] === true,
-        price_source: extras.s ?? "sale_price", quote_price_unverified: extras.u === true,
-        conflicted: extras.c === true,
-        ...(Array.isArray(extras.o) ? { price_observations_fen: extras.o } : {}),
-    };
-}
-function decodeRide(row, wait, stations, services) {
-    if (!Array.isArray(row)) {
-        const ride = asObject(row);
-        if (!Object.keys(ride).length)
-            throw new Error("rail catalog: malformed ride row");
-        const refs = Array.isArray(ride.service_refs) ? ride.service_refs : [];
-        const codes = [...new Set(refs.map((ref) => asObject(services[asString(ref) ?? ""]).tc)
-                .filter((code) => typeof code === "string" && code.length > 0))];
-        const departure = datedTime(ride.boarding_date, ride.departure_at ?? ride.departure);
-        const arrival = datedTime(ride.boarding_date, ride.arrival_at ?? ride.arrival);
-        return { train_codes: codes, train_code: codes.join("/"),
-            from_station: stations[asString(ride.from_station_code) ?? ""] ?? ride.from_station ?? null,
-            to_station: stations[asString(ride.to_station_code) ?? ""] ?? ride.to_station ?? null,
-            boarding_date: ride.boarding_date ?? null,
-            departure, arrival, duration_minutes: elapsedMinutes(departure, arrival),
-            wait_minutes: typeof wait === "number" ? wait : ride.wait_minutes ?? null,
-            same_run: ride.same_run === true, onboard_stops: Array.isArray(ride.onboard_stops) ? ride.onboard_stops : [],
-        };
-    }
-    const extras = asObject(row[8]);
-    const refs = Array.isArray(row[4]) ? row[4] : [];
-    const codes = [...new Set(refs.map((ref) => asObject(services[asString(ref) ?? ""]).tc)
-            .filter((code) => typeof code === "string" && code.length > 0))];
-    const base = row[0];
-    const departure = datedTime(base, extras.dep);
-    const arrival = datedTime(base, extras.arr);
-    return {
-        train_codes: codes, train_code: codes.join("/"),
-        from_station: stations[asString(row[2]) ?? ""] ?? row[2] ?? null,
-        to_station: stations[asString(row[3]) ?? ""] ?? row[3] ?? null,
-        boarding_date: base ?? null,
-        departure, arrival, duration_minutes: elapsedMinutes(departure, arrival),
-        wait_minutes: typeof wait === "number" ? wait : typeof row[5] === "number" ? row[5] : null,
-        same_run: row[6] === true, onboard_stops: Array.isArray(row[7]) ? row[7] : [],
-    };
-}
-function decodePlans(rawPlans, rawProfiles, packed, catalog, services, names, stations) {
-    const plans = Array.isArray(rawPlans) ? rawPlans : [];
-    const profiles = Array.isArray(rawProfiles) ? rawProfiles : [];
-    const preferred = profiles.find((profile) => Array.isArray(profile) && Array.isArray(profile[1]) && profile[1].includes("balanced")) ?? profiles[0];
-    const profile = Array.isArray(preferred) ? preferred : [];
-    const serviceIndex = Array.isArray(catalog.service_index) ? catalog.service_index : [];
-    const selectedPlan = packed && typeof profile[2] === "number" ? plans[asIndex(profile[2], plans.length)] :
-        plans.find((plan) => Array.isArray(plan) && plan[0] === profile[2]);
-    const selectedRef = Array.isArray(selectedPlan) ? selectedPlan[0] : null;
-    const decoded = plans.map((plan) => {
-        if (!Array.isArray(plan))
-            throw new Error("rail catalog: malformed ticket plan");
-        const refs = (Array.isArray(plan[1]) ? plan[1] : []).map((ref) => packed && typeof ref === "number" ? serviceIndex[asIndex(ref, serviceIndex.length)] : ref);
-        const extras = asObject(plan[7]);
-        const legs = refs.map((ref, index) => {
-            const service = asObject(services[asString(ref) ?? ""]);
-            const offers = Array.isArray(service.of) ? service.of : [];
-            const selectedOffer = plan[0] === selectedRef && Array.isArray(profile[3]) ? profile[3][index] : undefined;
-            const chosen = packed && typeof selectedOffer === "number" ? offers[asIndex(selectedOffer, offers.length)] :
-                offers.find((offer) => Array.isArray(offer) && offer[0] === selectedOffer);
-            return {
-                service_ref: ref ?? null, train_code: service.tc ?? null,
-                from_station: stations[asString(service.f) ?? ""] ?? service.f ?? null,
-                to_station: stations[asString(service.t) ?? ""] ?? service.t ?? null,
-                departure: datedTime(service.d, service.dep), arrival: datedTime(service.d, service.arr),
-                seat_options: offers.map((offer) => seatOffer(offer, names)).filter((offer) => offer !== null),
-                ...(chosen ? { selected_seat: seatOffer(chosen, names) } : {}),
-            };
-        });
-        const amount = asObject(plan[3]);
-        return {
-            ticket_plan_ref: plan[0], passenger_count: plan[2] ?? null,
-            purchase_support: plan[6] ?? "none", rail_amount_verified: plan[4] === true,
-            rail_amount_fen: { default: amount.def ?? null, minimum: amount.min ?? null, maximum: amount.max ?? null },
-            service_fee_fen: plan[5] ?? null, quote_price_unverified: extras.qu === true,
-            legs,
-        };
-    });
-    const selected = decoded.find((plan) => plan.ticket_plan_ref === selectedRef);
-    return { plans: decoded, ...(selected ? { selected } : {}) };
-}
-// _cn_route_text port: "南头 C7608 → 广州南换乘71分 → G2944 重庆西" — kept
-// byte-identical with the planner so a packed journey renders the same text
-// its object form carried.
-function regenerateRoute(ridePairs, rideTable, stations, services) {
-    const name = (code, fallback) => asString(stations[asString(code) ?? ""]) ?? asString(fallback) ?? asString(code) ?? "?";
-    const rides = ridePairs.map((pair) => {
-        if (!Array.isArray(pair) || pair.length !== 2)
-            throw new Error("shared_rows: malformed ride pair");
-        const src = rideTable[asIndex(pair[0], rideTable.length)];
-        if (!Array.isArray(src))
-            throw new Error("shared_rows: malformed ride row");
-        return { row: src, wait: pair[1] };
-    });
-    const first = rides[0];
-    if (first === undefined)
-        return "";
-    const trainCodes = (rideRow) => (Array.isArray(rideRow[4]) ? rideRow[4] : [])
-        .map((ref) => {
-        const svc = services[asString(ref) ?? ""];
-        return asString(svc?.tc);
-    })
-        .filter((c) => Boolean(c));
-    const waitOf = (ride) => typeof ride.wait === "number" ? ride.wait
-        : typeof ride.row[5] === "number" ? ride.row[5]
-            : undefined;
-    const sameRun = (rideRow) => rideRow[6] === true;
-    const parts = [`${name(first.row[2], undefined)} ${trainCodes(first.row).join("/")}`];
-    for (let i = 1; i < rides.length; i += 1) {
-        const prev = rides[i - 1].row;
-        const ride = rides[i];
-        const via = name(prev[3], undefined);
-        const wait = waitOf(ride);
-        parts.push(sameRun(ride.row)
-            ? wait !== undefined ? `${via}同车停${wait}分` : `${via}同车接续`
-            : wait !== undefined ? `${via}换乘${wait}分` : `${via}换乘`);
-        parts.push(`${trainCodes(ride.row).join("/")} ${name(ride.row[3], undefined)}`);
-    }
-    if (rides.length === 1) {
-        parts.push(name(first.row[3], undefined));
-    }
-    return parts.filter((s) => s.trim().length > 0).join(" → ");
-}
-// decodeRailCatalogJourneys returns one summary per committed combination in
-// catalog order. Legacy object-form catalogs (no `encoding`) pass through;
-// shared_rows.v1 rows are positional under journey_columns
-// [ref, route, rides, plans, gc, pr, profiles, tc, ev, rep, tw, risk].
-// Any other encoding throws RailCatalogEncodingError — an explicit upgrade
-// hint, never an empty catalog.
-export function decodeRailCatalogJourneys(catalog) {
-    const encoding = catalog["encoding"];
-    const layerMap = catalog["choice_layers"]?.["journey_layer"] ?? {};
-    const layerOf = (ref) => layerMap[ref] === "backup" ? "backup" : "main";
-    const stations = asObject(catalog.stations);
-    const services = asObject(catalog.services);
-    const seatNames = asObject(catalog.seat_names);
-    if (encoding === undefined || encoding === null) {
-        const rows = Array.isArray(catalog["journeys"]) ? catalog["journeys"] : [];
-        return {
-            packed: false,
-            journeys: rows.map((j) => {
-                const rec = (j ?? {});
-                const ref = asString(rec["ref"]) ?? asString(rec["journey_id"]) ?? "?";
-                const calculationScope = scopeFromProfiles(rec["profiles"]);
-                const rides = (Array.isArray(rec.rides) ? rec.rides : []).map((ride) => decodeRide(ride, null, stations, services));
-                const ticketPlans = decodePlans(rec.plans, rec.profiles, false, catalog, services, seatNames, stations);
-                return {
-                    ref,
-                    route: asString(rec["route"]) ?? asString(rec["route_text"]) ?? asString(rec["summary"]) ?? "",
-                    defaultLayer: layerOf(ref),
-                    rides,
-                    ...(calculationScope ? { calculation_scope: calculationScope } : {}),
-                    ticket_plans: ticketPlans.plans,
-                    ...(ticketPlans.selected ? { selected_plan: ticketPlans.selected } : {}),
-                };
-            }),
-        };
-    }
-    if (encoding !== "shared_rows.v1") {
-        throw new RailCatalogEncodingError(encoding);
-    }
-    const columns = catalog["journey_columns"];
-    if (!Array.isArray(columns) || columns[0] !== "ref" || columns[1] !== "route" || columns[2] !== "rides") {
-        throw new RailCatalogEncodingError(`${String(encoding)} (unexpected journey_columns)`);
-    }
-    const rideTable = (Array.isArray(catalog["ride_table"]) ? catalog["ride_table"] : []);
-    const journeys = (Array.isArray(catalog["journeys"]) ? catalog["journeys"] : []);
-    return {
-        packed: true,
-        journeys: journeys.map((row) => {
-            if (!Array.isArray(row))
-                throw new Error("shared_rows: journey row is not an array");
-            const ref = asString(row[0]) ?? "?";
-            const route = asString(row[1]) ??
-                (Array.isArray(row[2]) ? regenerateRoute(row[2], rideTable, stations, services) : "");
-            const rides = (Array.isArray(row[2]) ? row[2] : []).map((pair) => {
-                if (!Array.isArray(pair) || pair.length !== 2)
-                    throw new Error("shared_rows: malformed ride pair");
-                return decodeRide(rideTable[asIndex(pair[0], rideTable.length)], pair[1], stations, services);
-            });
-            const calculationScope = scopeFromProfiles(row[6]);
-            const ticketPlans = decodePlans(row[3], row[6], true, catalog, services, seatNames, stations);
-            return { ref, route, defaultLayer: layerOf(ref), rides,
-                ...(calculationScope ? { calculation_scope: calculationScope } : {}),
-                ticket_plans: ticketPlans.plans,
-                ...(ticketPlans.selected ? { selected_plan: ticketPlans.selected } : {}) };
-        }),
-    };
-}
+export * from "../services/rail/catalog.js";

package/dist/src/commands/readyz.js

@@ -8,8 +8,8 @@ export async function runReadyz(backend, options = {}) {
         status: response.status,
         result: { backend: "available", backend_url: backendURL, environment, ...(options.agentType ? { agent_type: options.agentType } : {}) },
         instruction: environment === "development"
-            ? `ItPay 开发环境 ${backendURL} 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；后续必须执行返回的完整命令并保持同一 Backend。`
-            : "ItPay 可用。先完整读取内置 Skill，再根据用户意图选择新服务、已购内容、订单或退款入口；不要默认开始购买。",
+            ? `ItPay 开发环境 ${backendURL} 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；后续必须执行返回的完整命令并保持同一 Backend。`
+            : "ItPay 可用。只证明后端存活。尚未读此次包 Skill 时完整读取；已读同版本则无需重复，继续设备状态检查；不自动登录或开始业务。",
         next: { command: "itpay skill show itpay --json", reason: "加载完整操作与安全规则" },
         recovery: [],
     }, options);

package/dist/src/commands/refund.js

@@ -1,3 +1,4 @@
+import { refundStateEnvelope } from "../services/shared/refund.js";
 import { operationID } from "../state/config.js";
 import { formatMoney } from "../render/output.js";
 import { resolveOutput } from "../render/sink.js";
@@ -12,46 +13,6 @@ export async function runRefund(backend, config, options) {
         plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
     });
 }
-export function refundStateEnvelope(refund, status) {
-    const terminal = ["succeeded", "failed", "cancelled", "rejected"].includes(refund.status);
-    let instruction = refund.decision_mode === "manual"
-        ? "先告诉用户退款已进入人工审核，原交付保持冻结；人工审核不等于拒绝，等待服务器决定，不要重复申请或承诺结果。"
-        : "先告诉用户退款申请已经记录，原交付已冻结；自动路径表示系统会继续处理，但只有最终 succeeded 才能确认退款成功。然后只跟踪同一退款，不读取交付、不创建授权或重复申请。";
-    if (!refund.access_locked)
-        instruction = "先告诉用户退款当前没有锁定交付；按服务器事实解释当前状态，不要自行推断退款结果、到账时间或交付资格。";
-    if (refund.status === "succeeded")
-        instruction = "先告诉用户退款已由 ItPay 确认成功，原交付永久关闭；不需要继续跟踪或重复申请。";
-    if (refund.status === "cancelled" || refund.status === "rejected")
-        instruction = "先告诉用户退款没有执行，交付资格可以恢复；旧读取授权不会复活，需要用户重新授权。不要把取消或拒绝说成退款成功。";
-    if (refund.status === "failed") {
-        if (refund.failure_class === "known_no_effect")
-            instruction = "先告诉用户本次退款请求确认未发送，不能说退款已成功；Agent 不自行重试，请用户等待平台管理员决定是否重新执行。";
-        else if (refund.failure_class === "retryable")
-            instruction = "先告诉用户渠道明确返回可重试失败，但 Agent 不会自行重试或重复申请；请用户等待平台管理员处理。";
-        else if (refund.failure_class === "outcome_unknown")
-            instruction = "先告诉用户退款渠道结果未知，原交付继续锁定且必须先由平台对账；禁止重试、重复申请或承诺退款结果。";
-        else if (refund.failure_class === "permanent")
-            instruction = "先告诉用户渠道明确拒绝本次退款，当前不能承诺退款成功；不要重试，请用户联系平台支持。";
-        else
-            instruction = "先告诉用户退款没有正常完成，当前不能承诺退款成功；不要重试或重复申请，请用户联系平台支持。";
-    }
-    return {
-        status,
-        result: {
-            refund_request_id: refund.refund_request_id,
-            order_id: refund.order_id,
-            decision_mode: refund.decision_mode,
-            refund_status: refund.status,
-            consumption_state: refund.consumption_state,
-            ...(refund.failure_class ? { failure_class: refund.failure_class } : {}),
-            access_locked: refund.access_locked,
-            can_cancel: refund.can_cancel,
-        },
-        instruction,
-        next: terminal ? null : { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "跟踪同一退款" },
-        recovery: [],
-    };
-}
 export async function runListRefunds(backend, options) {
     const out = resolveOutput(options.output);
     const response = await backend.listOrderRefunds(options.orderID);
@@ -110,36 +71,30 @@ export async function runCancelRefund(backend, refundID, reason, options = {}) {
 }
 export async function runWatchRefund(backend, refundID, options = {}) {
     const intervalSeconds = options.intervalSeconds ?? 2;
-    const timeoutSeconds = options.timeoutSeconds ?? 120;
+    const timeoutSeconds = options.timeoutSeconds ?? 20;
     if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1)
         throw new Error("--interval must be at least 1 second");
     if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)
         throw new Error("--timeout must be a positive number");
     const deadline = Date.now() + timeoutSeconds * 1000;
     let refund;
+    let initialState;
     for (;;) {
         refund = await backend.getRefund(refundID);
-        if (["succeeded", "failed", "cancelled", "rejected"].includes(refund.status)) {
+        const state = JSON.stringify([refund.status, refund.decision_mode, refund.failure_class, refund.access_locked, refund.can_cancel]);
+        if (["succeeded", "failed", "cancelled", "rejected"].includes(refund.status) || refund.decision_mode === "manual" || refund.failure_class === "outcome_unknown" || (initialState !== undefined && state !== initialState)) {
             writeRefundEnvelope(refundStateEnvelope(refund, "watch_complete"), options);
             return;
         }
+        initialState ??= state;
         const remaining = deadline - Date.now();
         if (remaining <= 0)
             break;
         await new Promise((resolve) => setTimeout(resolve, Math.min(intervalSeconds * 1000, remaining)));
     }
-    writeRefundEnvelope({
-        status: "watch_timeout",
-        result: {
-            refund_request_id: refund.refund_request_id,
-            last_status: refund.status,
-            access_locked: refund.access_locked,
-            can_cancel: refund.can_cancel,
-        },
-        instruction: "先告诉用户退款仍在处理，Timeout 只表示本次等待结束，并不表示退款失败；稍后继续跟踪同一退款，不要重复申请或承诺结果。",
-        next: { command: `itpay refund watch ${refund.refund_request_id} --json`, reason: "恢复轮询" },
-        recovery: [],
-    }, options);
+    const latest = refundStateEnvelope(refund, "watch_timeout");
+    writeRefundEnvelope({ ...latest, result: { ...latest.result, last_status: refund.status, wait_ended: true },
+        instruction: `本次等待结束，并不表示退款失败。${latest.instruction} 稍后按需读取同一退款，不自动重启等待，不要重复申请。` }, options);
 }
 function writeRefundEnvelope(envelope, options) {
     writeCommandEnvelope(envelope, {
@@ -148,3 +103,4 @@ function writeRefundEnvelope(envelope, options) {
         plainResult: Object.entries(envelope.result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`),
     });
 }
+export { refundStateEnvelope } from "../services/shared/refund.js";

package/dist/src/commands/services/actions.js

@@ -0,0 +1,133 @@
+import { serviceAdapter } from "../../services/registry.js";
+import { CommandContractError, writeCommandEnvelope } from "../../services/shared/envelope.js";
+import { normalizeServiceActionStatus, paidContinuation, serviceAllowedActionCommand, purchaseConfirmationInstruction, actionInputError } from "../../services/shared/platform.js";
+import { servicesNextEnvelope } from "../../services/presentation.js";
+export async function runServicesAction(backend, serviceExecutionID, actionType, input, options = {}) {
+    const selection = await resolveCandidateSelection(backend, serviceExecutionID, actionType, options);
+    const request = {
+        action_type: actionType,
+        input_snapshot: input,
+    };
+    if (options.actorType)
+        request.actor_type = options.actorType;
+    if (options.actorID)
+        request.actor_id = options.actorID;
+    if (options.status)
+        request.status = normalizeServiceActionStatus(options.status, serviceExecutionID);
+    const resultItemID = selection?.resultItemID ?? options.resultItemID;
+    if (resultItemID)
+        request.result_item_id = resultItemID;
+    if (options.requiredBefore)
+        request.required_before = options.requiredBefore;
+    let response;
+    try {
+        response = await backend.recordServiceExecutionAction(serviceExecutionID, request);
+    }
+    catch (error) {
+        // A failed write is never replayed. Only the locked execution identifies its adapter.
+        try {
+            const model = await backend.getServiceExecution(serviceExecutionID);
+            serviceAdapter(model.execution).actionError(error, serviceExecutionID, actionType);
+        }
+        catch (recoveryError) {
+            if (recoveryError instanceof CommandContractError)
+                throw recoveryError;
+        }
+        throw error;
+    }
+    if (actionType === "approve_purchase" && "status" in response && response.status === "approved") {
+        const quoteID = typeof input.service_quote_lock_id === "string" ? input.service_quote_lock_id : "";
+        writeCommandEnvelope({
+            status: "purchase_preparation_approved",
+            result: { service_execution_id: serviceExecutionID, evidence_source: "agent_reported", scope: "prepare_checkout", service_quote_lock_id: quoteID },
+            instruction: "已记录同范围的准备付款入口批准；这是Agent报告的真实会话同意，不是已付款或出票。继续使用本报价；条件未变不重复询问，官方页实际支付仍由用户完成。",
+            next: quoteID ? { command: `itpay cart add --quote ${quoteID} --json`, reason: "加入本次已批准报价，准备同一个付款入口" } : null,
+            recovery: [{ command: `itpay services next ${serviceExecutionID} --json`, reason: "读取原执行与付款状态，不重新购买" }],
+        }, { ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}), ...(options.output ? { output: options.output } : {}) });
+        return;
+    }
+    if ("state" in response) {
+        const updated = await backend.getServiceExecution(serviceExecutionID);
+        const envelope = servicesNextEnvelope(updated);
+        envelope.result = {
+            ...envelope.result,
+            planning_action: { action_id: response.action_id, state: response.state, replayed: response.replayed },
+        };
+        writeCommandEnvelope(envelope, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
+    if (selection && actionType === "select_candidate" && response.status === "approved") {
+        const updated = await backend.getServiceExecution(serviceExecutionID);
+        const preferred = updated.allowed_actions?.[0];
+        const continuation = preferred?.type === "prepare_quote"
+            ? paidContinuation(updated, preferred, {})
+            : null;
+        const next = continuation?.next ?? (preferred ? serviceAllowedActionCommand(updated, preferred) : null);
+        writeCommandEnvelope({
+            status: "candidate_selected",
+            result: {
+                service_execution_id: response.service_execution_id,
+                candidate: { rank: selection.rank, title: selection.title },
+                ...(continuation ? { checkout: continuation.checkout } : {}),
+            },
+            instruction: continuation
+                ? purchaseConfirmationInstruction("candidate_selected", continuation.price, continuation.capability.delivery_email_required, continuation.capability.delivery_email_purpose, selection.title)
+                : "候选已绑定到来源 Execution；后续动作必须继续使用该 Execution。",
+            next,
+            recovery: [{
+                    command: `itpay services next ${response.service_execution_id} --json`,
+                    reason: "重新读取服务端允许的动作",
+                }],
+        }, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+        });
+        return;
+    }
+    writeCommandEnvelope({
+        status: "action_recorded",
+        result: {
+            service_execution_id: response.service_execution_id,
+            action_type: response.action_type,
+            action_status: response.status,
+            evidence_source: "agent_reported",
+            reported_actor_type: response.actor_type,
+        },
+        instruction: "动作已记录（Agent转述；actor_type并非官方页面真人确认的证明）。读取服务端计算的新状态；不要自行假设下一 capability。",
+        next: {
+            command: `itpay services next ${response.service_execution_id} --json`,
+            reason: "取得更新后的首选动作",
+        },
+        recovery: [],
+    }, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+    });
+}
+export async function resolveCandidateSelection(backend, serviceExecutionID, actionType, options) {
+    if (options.candidateRank === undefined)
+        return undefined;
+    if (actionType !== "select_candidate") {
+        throw actionInputError(serviceExecutionID, "--candidate is only valid with --action select_candidate");
+    }
+    if (options.resultItemID) {
+        throw actionInputError(serviceExecutionID, "--candidate cannot be combined with --result-item");
+    }
+    if (!Number.isInteger(options.candidateRank) || options.candidateRank < 1) {
+        throw actionInputError(serviceExecutionID, "--candidate must be a positive integer result rank");
+    }
+    const execution = await backend.getServiceExecution(serviceExecutionID);
+    const currentItems = execution.current_result_items ?? [];
+    const result = currentItems.find((item) => item.rank === options.candidateRank);
+    if (!result) {
+        throw actionInputError(serviceExecutionID, `candidate ${options.candidateRank} is not available on service execution ${serviceExecutionID}`, "candidate_not_found");
+    }
+    return {
+        resultItemID: result.service_capability_result_item_id,
+        rank: result.rank,
+        title: result.display_title,
+    };
+}