@itpay/cli 2.0.31 → 2.0.33

package/README.md

@@ -8,13 +8,23 @@ The official V3 CLI and the single ItPay entry point for services, purchases, ac
 
 ```bash
 npm install -g @itpay/cli
-itpay readyz --json
-itpay skill show itpay --json
 itpay install --json
 itpay --agent-type codex-desktop readyz --json
-# read the typed Skill, understand the human's intent, then choose the first command
+# execute the returned next.command until the typed Skill is loaded
 ```
 
+Official Agent install prompt（可直接复制给 Agent）：
+
+> 安装或更新官方 `@itpay/cli`。从 `itpay install --json` 开始，选择你真实
+> 所在的平台，完整执行 iTPay 返回的每个 `next.command` 并读取内置 Skill。
+> 初始化后，根据我的自然语言需求自行使用 iTPay，不要让我运行命令，也不要向
+> 我讲解命令、内部 ID 或技术步骤。只有需要我选择、授权、付款、提供联系方式
+> 或确认退款时，才用通俗语言询问我；展示官方操作入口后停止等待。不要猜命令、
+> 切换身份或环境、绕过授权或重复创建资源。准备完成后只回复“iTPay 已就绪”。
+
+Use a separate test prompt to set the exact official Dev Backend. Never put a
+Dev override in the public install prompt.
+
 The CLI defaults to the production Backend `https://app.itpay.ai`. Explicit tests may set `ITPAY_BACKEND_URL=https://dev.itpay.ai`; every other Backend URL is rejected before network or local state access.
 
 ## Output Contract

package/dist/src/client/backend.js

@@ -58,6 +58,9 @@ export class BackendClient {
     getOrderDeliveryAccess(orderID) {
         return this.http.get(`/v1/orders/${encodeURIComponent(orderID)}/delivery-access`);
     }
+    submitServiceFeedback(orderID, input) {
+        return this.http.post(`/v1/orders/${encodeURIComponent(orderID)}/feedback`, input);
+    }
     listAccountOrders(limit, status, bearer, cursor) {
         const qs = new URLSearchParams({ limit: String(limit) });
         if (status) {

package/dist/src/commands/checkout.js

@@ -110,7 +110,7 @@ function terminalCheckoutEnvelope(presentation) {
     const recovery = [];
     if (payment === "verified") {
         status = "completed";
-        instruction = "先告诉用户：付款已经确认，订单已经记录，不需要再次付款；结果会在同一订单下继续准备，如果最终无法正常交付，可以从原订单申请退款，处理方式由内容是否已使用决定。然后只执行 next.command 读取同一 Execution；不要再次展示付款入口、调用 pay 或创建新 Checkout/Execution，也不要承诺退款结果。";
+        instruction = "告诉用户：付款已经确认，订单已经记录，不需要再次付款；结果会在同一订单下继续准备，如果最终无法交付，可以从原订单申请退款，处理方式由内容是否已使用决定。然后只执行 next.command 读取同一笔服务；Agent 不再展示付款入口或创建新订单，也不承诺退款结果。";
         next = serviceExecutionIDs.length === 1
             ? { command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "读取同一笔已付款 Service Execution" }
             : presentation.completed_order_id

package/dist/src/commands/feedback.js

@@ -0,0 +1,143 @@
+import { CLI_VERSION } from "../state/config.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+const MAX_FEEDBACK_NOTE_CODE_POINTS = 2000;
+export async function runFeedbackSubmit(backend, orderID, options) {
+    const normalizedOrderID = orderID?.trim() ?? "";
+    if (!normalizedOrderID) {
+        throw new CommandContractError("order_required", "--order is required", "先恢复用户所说的原订单；Agent 自己取得订单，不要求用户提供内部 ID。本次未提交反馈。", [{ command: "itpay orders --json", reason: "列出当前授权账号的订单摘要" }]);
+    }
+    const rating = normalizeFeedbackRating(options.rating);
+    const itemRank = normalizeItemRank(options.itemRank);
+    const userNote = normalizeUserNote(options.note ?? "");
+    const order = await backend.getOrder(normalizedOrderID);
+    const choices = feedbackItemChoices(order);
+    if (choices.length === 0) {
+        throw new CommandContractError("feedback_unavailable", "this order has no service item available for feedback", "告诉用户这笔订单当前没有可评价的服务项目并停止；不要猜测项目 ID、切换身份或创建其他反馈。", []);
+    }
+    if (choices.length > 1 && itemRank === undefined) {
+        writeCommandEnvelope({
+            status: "feedback_item_selection_required",
+            result: {
+                ...(order.order_code ? { order_code: order.order_code } : {}),
+                items: choices.map(({ rank, title, subject }) => ({ rank, title, ...(subject ? { subject } : {}) })),
+            },
+            instruction: "用服务名称和主题让用户选择要评价哪一项；不要展示内部 ID。用户选择后，Agent 使用同一订单、评分和留言并加入所选 item rank 自己执行提交。",
+            next: null,
+            recovery: [],
+        }, outputOptions(options));
+        return;
+    }
+    const choice = itemRank === undefined
+        ? choices[0]
+        : choices.find((candidate) => candidate.rank === itemRank);
+    if (!choice) {
+        throw new CommandContractError("feedback_item_invalid", `item rank ${itemRank} is not available for feedback`, "只使用当前订单返回的服务项目编号；不要猜测内部 ID。本次未提交反馈。", []);
+    }
+    const note = formatFeedbackNote({
+        userNote,
+        outcome: order.status,
+        serviceTitle: choice.title,
+        environment: options.environment,
+        ...(options.agentType ? { agentType: options.agentType } : {}),
+    });
+    if (codePointLength(note) > MAX_FEEDBACK_NOTE_CODE_POINTS) {
+        throw new CommandContractError("feedback_note_too_long", `formatted feedback note exceeds ${MAX_FEEDBACK_NOTE_CODE_POINTS} Unicode code points`, "请用户缩短反馈内容；不要截断、改写或拆分提交。本次未提交反馈。", []);
+    }
+    const response = await backend.submitServiceFeedback(normalizedOrderID, {
+        order_item_id: choice.item.order_item_id,
+        rating,
+        note,
+    });
+    writeCommandEnvelope({
+        status: "feedback_submitted",
+        result: {
+            ...(order.order_code ? { order_code: order.order_code } : {}),
+            service_title: choice.title,
+            rating: response.feedback.rating,
+            feedback_status: response.feedback.status,
+        },
+        instruction: "告诉用户反馈已经记录并表示感谢，然后停止。不要承诺回复、处理时间、退款或结果变更。",
+        next: null,
+        recovery: [],
+    }, outputOptions(options));
+}
+export function normalizeFeedbackRating(value) {
+    const normalized = value?.trim().toLowerCase() ?? "";
+    const numeric = normalized.match(/^([1-5])(?:\s*(?:\/\s*5|分|星|stars?))?$/u);
+    if (numeric)
+        return Number(numeric[1]);
+    const chinese = normalized.match(/^([一二三四五])(?:分|星)?$/u)?.[1];
+    if (chinese)
+        return { 一: 1, 二: 2, 三: 3, 四: 4, 五: 5 }[chinese];
+    throw new CommandContractError("feedback_rating_invalid", "--rating must be an explicit score from 1 to 5", "请用户明确给出 1–5 分；不要从好评、差评或情绪推断评分。本次未提交反馈。", []);
+}
+function normalizeItemRank(value) {
+    if (value === undefined)
+        return undefined;
+    const match = value.trim().match(/^#?([1-9]\d*)$/u);
+    if (!match) {
+        throw new CommandContractError("feedback_item_invalid", "--item-rank must be a positive integer", "使用当前订单返回的正整数服务项目编号；本次未提交反馈。", []);
+    }
+    const rank = Number(match[1]);
+    if (!Number.isSafeInteger(rank)) {
+        throw new CommandContractError("feedback_item_invalid", "--item-rank is outside the supported integer range", "使用当前订单返回的服务项目编号；本次未提交反馈。", []);
+    }
+    return rank;
+}
+function feedbackItemChoices(order) {
+    return order.items.flatMap((item, index) => {
+        if (!item.order_item_id?.trim())
+            return [];
+        const subject = feedbackSubject(item);
+        return [{
+                rank: index + 1,
+                item,
+                title: safeLine(item.title) || "未命名服务",
+                ...(subject ? { subject } : {}),
+            }];
+    });
+}
+function feedbackSubject(item) {
+    for (const field of ["company_name_or_credit_no", "company_name", "company", "target", "keyword"]) {
+        const value = item.input?.[field];
+        if (typeof value === "string") {
+            const safe = safeLine(value);
+            if (safe)
+                return safe.slice(0, 160);
+        }
+    }
+    return undefined;
+}
+function normalizeUserNote(value) {
+    return value
+        .replaceAll("\r\n", "\n")
+        .replaceAll("\r", "\n")
+        .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/gu, " ")
+        .trim();
+}
+function formatFeedbackNote(input) {
+    const summary = input.userNote
+        ? `## Summary\n${input.userNote.split("\n").map((line) => `> ${line}`).join("\n")}\n\n`
+        : "";
+    return `${summary}## Context\n` + [
+        "- Source: user-confirmed via agent",
+        `- Outcome: ${safeLine(input.outcome) || "unknown"}`,
+        `- Service: ${safeLine(input.serviceTitle) || "未命名服务"}`,
+        `- Client: @itpay/cli ${CLI_VERSION}`,
+        `- Agent type: ${safeLine(input.agentType ?? "unspecified")}`,
+        `- Environment: ${input.environment}`,
+    ].join("\n");
+}
+function safeLine(value) {
+    return value.replace(/[\r\n\u0000-\u001F\u007F]+/gu, " ").trim();
+}
+function codePointLength(value) {
+    return Array.from(value).length;
+}
+function outputOptions(options) {
+    return {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        ...(options.agentType ? { agentType: options.agentType } : {}),
+    };
+}

package/dist/src/commands/guidance.js

@@ -5,6 +5,12 @@ import { qualifyBackendCommand } from "../state/config.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
+export function appendOptionalFeedbackInvitation(instruction, outcome) {
+    const invitation = outcome === "delivered"
+        ? "结果解释完毕后，可以询问用户是否愿意给这次服务 1–5 分和一句可选建议。只有用户明确评分后，Agent 才使用同一订单提交反馈；不要展示命令或内部 ID，同一对话最多询问一次。"
+        : "先完成同一订单的恢复和退款权利解释；处理清楚后，可以询问用户是否愿意给 1–5 分并说明卡壳点。只有用户明确评分后才提交反馈，同一对话最多询问一次。";
+    return `${instruction} ${invitation}`;
+}
 export class CommandContractError extends Error {
     code;
     instruction;
@@ -57,49 +63,6 @@ export function writeCommandEnvelope(value, options = {}) {
         }
     }
 }
-export function attachAgentGuidance(payload, guidance) {
-    return {
-        ...payload,
-        agent_guidance: 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");
-        for (const item of guidance.visible_results) {
-            out(`  ${item.rank}. ${item.title}\n`);
-            for (const [key, value] of Object.entries(item.safe_payload)) {
-                if (key === "name" || key === "company_name" || value === "" || value === undefined || value === null)
-                    continue;
-                out(`     ${key}: ${String(value)}\n`);
-            }
-        }
-    }
-    if (guidance.next_actions.length === 0) {
-        out("next actions: none\n");
-    }
-    else {
-        out("next actions:\n");
-        for (const action of guidance.next_actions) {
-            out(`  - ${action.label}\n`);
-            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
-            if (action.requires_human)
-                out("    requires human confirmation\n");
-            if (action.reason)
-                out(`    reason: ${action.reason}\n`);
-        }
-    }
-    if (guidance.recovery.length > 0) {
-        out("recovery:\n");
-        for (const action of guidance.recovery) {
-            out(`  - ${action.label}\n`);
-            out(`    ${qualifyBackendCommand(qualifyItPayCommand(action.command, agentType))}\n`);
-        }
-    }
-}
 function qualifyEnvelope(value, agentType) {
     return {
         ...value,
@@ -110,181 +73,31 @@ function qualifyEnvelope(value, agentType) {
         })),
     };
 }
-export function buildCartGuidance(cart, serviceModel) {
-    const serviceLine = latestServiceLine(cart);
-    if (serviceLine?.service_execution_id) {
-        const serviceGuidance = serviceModel
-            ? buildServiceReadModelGuidance(serviceModel)
-            : buildServiceHandleGuidance(serviceLine.service_execution_id, serviceLine.service_capability_id);
-        return {
-            ...serviceGuidance,
-            kind: "cart_service_execution",
-            summary: `cart ${cart.cart_id}: service-backed line ${lineID(serviceLine)} is ready for Service Execution`,
-            state: {
-                ...serviceGuidance.state,
-                cart_id: cart.cart_id,
-                cart_item_id: lineID(serviceLine),
-                service_capability_id: serviceLine.service_capability_id,
-            },
-        };
-    }
-    if (cart.items.length === 0) {
-        return {
-            kind: "empty_cart",
-            summary: `cart ${cart.cart_id}: empty`,
-            state: { cart_id: cart.cart_id, status: cart.status },
-            next_actions: [
-                {
-                    id: "browse_catalog",
-                    label: "Browse services",
-                    command: "itpay catalog list",
-                },
-            ],
-            recovery: [],
-        };
-    }
-    return {
-        kind: "cart_checkout_ready",
-        summary: `cart ${cart.cart_id}: ready for checkout`,
-        state: { cart_id: cart.cart_id, status: cart.status, amount_minor: cart.amount_minor, currency: cart.currency },
-        next_actions: [
-            {
-                id: "checkout_cart",
-                label: "Create ItPay checkout",
-                command: `itpay buy --cart ${cart.cart_id} --host <client> --contact-email <email>`,
-                requires_human: true,
-                reason: "The human must review and pay on the ItPay checkout page.",
-            },
-        ],
-        recovery: [
-            {
-                id: "show_cart",
-                label: "Inspect current server cart",
-                command: "itpay cart show",
-            },
-        ],
-    };
-}
-export function buildServiceStartedGuidance(response) {
-    return buildServiceGuidance({
-        execution: response.execution,
-        capabilities: response.capabilities,
-    });
-}
-export function buildServiceReadModelGuidance(model) {
-    return buildServiceGuidance({
-        execution: model.execution,
-        capabilities: model.capabilities,
-        resultItems: model.result_items,
-        checkoutBindings: model.checkout_bindings,
-        deliveryBindings: model.delivery_bindings,
-    });
-}
-export function buildServiceInvokedGuidance(response, capabilities = []) {
-    return buildServiceGuidance({
-        execution: response.execution,
-        capabilities,
-        resultItems: response.result_items,
-        ...(response.next_actions ? { backendNextActions: response.next_actions } : {}),
-        ...(response.effective_quota ? { effectiveQuota: response.effective_quota } : {}),
-        providerCalled: response.provider_called,
-    });
-}
-export function buildServiceActionGuidance(action) {
-    const serviceExecutionID = action.service_execution_id;
-    return {
-        kind: "service_action_recorded",
-        summary: `service execution ${serviceExecutionID}: action ${action.action_type} recorded`,
-        state: {
-            service_execution_id: serviceExecutionID,
-            action_type: action.action_type,
-            status: action.status,
-            result_item_id: action.result_item_id,
-        },
-        next_actions: [
-            {
-                id: "inspect_service_execution",
-                label: "Read updated Service Execution state",
-                command: `itpay services next ${serviceExecutionID} --json`,
-            },
-        ],
-        recovery: [
-            {
-                id: "timeline",
-                label: "Inspect full timeline",
-                command: `itpay services get ${serviceExecutionID}`,
-            },
-        ],
-    };
-}
-export function buildServiceHandleGuidance(serviceExecutionID, checkoutCapabilityID) {
-    const actions = [
-        {
-            id: "inspect_service_execution",
-            label: "Read Service Execution state and capabilities",
-            command: `itpay services next ${serviceExecutionID} --json`,
-        },
-    ];
-    if (checkoutCapabilityID) {
-        actions.push({
-            id: "checkout_service",
-            label: "Create checkout after human confirmation",
-            command: `itpay services checkout ${serviceExecutionID} --capability ${checkoutCapabilityID} --json`,
-            requires_human: true,
-            reason: "Inspect the Service Execution first; the CLI will request delivery contact only when the selected capability requires it.",
-        });
-    }
-    return {
-        kind: "service_execution_handle",
-        summary: `service execution ${serviceExecutionID}: inspect before invoking`,
-        state: { service_execution_id: serviceExecutionID },
-        next_actions: actions,
-        recovery: [],
-    };
-}
 export function errorRecoveryActions(error) {
     if (!(error instanceof HttpError))
         return [];
     if (error.code === "agent_identity_required") {
-        return [
-            {
-                id: "inspect_agent_setup",
-                label: "Inspect supported Agent Type setup",
-                command: "itpay install --json",
-            },
-        ];
+        return [{ id: "inspect_agent_setup", label: "Inspect supported Agent Type setup", command: "itpay install --json" }];
     }
     if (error.code === "agent_device_session_required") {
-        return [
-            {
+        return [{
                 id: "read_agent_session_rules",
                 label: "Read ItPay identity and session recovery rules",
                 command: "itpay skill show itpay --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 [
-            {
+        return [{
                 id: "inspect_service_execution",
                 label: "Inspect Service Execution before checkout",
                 command: "itpay services next <service_execution_id> --json",
-            },
-        ];
+            }];
     }
     if (error.code === "cart_item_locked" || error.status === 409) {
         return [
-            {
-                id: "show_cart",
-                label: "Inspect the canonical server cart",
-                command: "itpay cart show",
-            },
-            {
-                id: "continue_checkout",
-                label: "Continue the last locally remembered checkout",
-                command: "itpay checkout",
-            },
+            { id: "show_cart", label: "Inspect the canonical server cart", command: "itpay cart show" },
+            { id: "continue_checkout", label: "Continue the last locally remembered checkout", command: "itpay checkout" },
             {
                 id: "recover_service_execution",
                 label: "List recoverable Service Executions if the local handoff is missing",
@@ -293,22 +106,18 @@ export function errorRecoveryActions(error) {
         ];
     }
     if (error.status === 404) {
-        return [
-            {
+        return [{
                 id: "recover_service_executions",
                 label: "List visible Service Executions and follow their next instruction",
                 command: "itpay services list",
-            },
-        ];
+            }];
     }
     if (error.status === 502 || error.status === 503 || error.status === 504) {
-        return [
-            {
+        return [{
                 id: "retry_after_backend_recovers",
                 label: "Retry after the selected official Backend is reachable",
                 command: "itpay readyz",
-            },
-        ];
+            }];
     }
     return [];
 }
@@ -323,207 +132,3 @@ export function printErrorRecovery(error, output) {
         out(`    ${action.command}\n`);
     }
 }
-function buildServiceGuidance(input) {
-    const execution = input.execution;
-    const capabilities = input.capabilities ?? [];
-    const prePurchase = firstPrePurchaseCapability(capabilities);
-    const paid = firstPaidCapability(capabilities);
-    const resultItem = input.resultItems?.[0];
-    const checkoutID = input.checkoutBindings?.at(-1)?.checkout_id;
-    const delivery = input.deliveryBindings?.[0];
-    const deliveryMode = String(delivery?.redacted_summary?.delivery_mode ?? (delivery?.vault_artifact_id ? "vault_artifact" : ""));
-    const backendCheckout = input.backendNextActions?.find((action) => action.kind === "create_checkout");
-    const nextActions = [];
-    const recovery = [
-        {
-            id: "timeline",
-            label: "Inspect full timeline",
-            command: `itpay services get ${execution.service_execution_id}`,
-        },
-    ];
-    if (isTerminalServiceExecutionStatus(execution.status)) {
-        // Terminal executions are inspectable, but no command may advance or replay them.
-    }
-    else if (deliveryMode === "agent_visible_result" && (input.resultItems?.length ?? 0) > 0) {
-        nextActions.push({
-            id: "use_agent_visible_result",
-            label: "Use the safe candidate list shown above",
-            command: `itpay services next ${execution.service_execution_id} --json`,
-            reason: "This result is already visible to the agent. Do not call services read-result; that command is only for Vault deliveries authorized by a human.",
-        });
-    }
-    else if (execution.status === "completed" || execution.next_action === "completed") {
-        nextActions.push({
-            id: "inspect_order_or_grant",
-            label: "Inspect order, claim, or grant from the checkout/order owner",
-            command: "itpay orders --limit 20",
-            requires_human: true,
-            reason: "Delivery visibility is controlled by the human account and grant flow.",
-        });
-    }
-    else if (execution.phase === "delivery" || execution.next_action === "view_delivery") {
-        const grantStatus = String(delivery?.grant_status ?? "");
-        if (grantStatus === "active") {
-            nextActions.push({
-                id: "read_granted_result",
-                label: "Read the human-granted service result",
-                command: `itpay services read-result ${execution.service_execution_id}`,
-                reason: "The human granted temporary agent access to this delivery.",
-            });
-        }
-        else {
-            nextActions.push({
-                id: grantStatus === "expired" ? "ask_human_to_reauthorize" : "wait_for_human_agent_grant",
-                label: grantStatus === "expired" ? "Ask the human to authorize AI access again" : "Wait for human AI-access authorization",
-                command: `itpay services get ${execution.service_execution_id}`,
-                requires_human: true,
-                reason: grantStatus === "expired"
-                    ? "The 15 minute human grant expired."
-                    : "The human must approve AI access on the Credential page.",
-            });
-        }
-    }
-    else if (execution.next_action === "pay_checkout" || execution.status === "checkout_pending") {
-        nextActions.push({
-            id: "open_existing_checkout",
-            label: "Open the existing ItPay checkout handoff",
-            command: `itpay services checkout ${execution.service_execution_id} --resume --json`,
-            requires_human: true,
-            reason: checkoutID
-                ? `Checkout ${checkoutID} already exists; reissue a short-lived handoff without creating another checkout.`
-                : "Recover the existing checkout handoff from Service Execution owner facts.",
-        });
-    }
-    else if (execution.checkout_required || execution.next_action === "create_checkout") {
-        const capabilityID = backendCheckout?.capability_id ?? paid?.capability_id ?? input.checkoutCapabilityID ?? execution.current_capability_id;
-        if (capabilityID) {
-            const checkoutCapability = capabilities.find((capability) => capability.capability_id === capabilityID);
-            const emailRequired = checkoutCapability?.delivery_email_required === true;
-            nextActions.push({
-                id: "checkout_service",
-                label: "Create ItPay checkout for the paid service capability",
-                command: `itpay services checkout ${execution.service_execution_id} --capability ${capabilityID}${emailRequired ? " --email <email>" : ""} --json`,
-                requires_human: true,
-                reason: emailRequired
-                    ? deliveryEmailGuidance(checkoutCapability?.delivery_email_purpose)
-                    : "This capability returns an agent-visible result after payment and does not require a delivery email.",
-            });
-        }
-        else {
-            nextActions.push({
-                id: "inspect_capabilities",
-                label: "Inspect capabilities before checkout",
-                command: `itpay services get ${execution.service_execution_id}`,
-            });
-        }
-    }
-    else if ((input.providerCalled || execution.next_action === "select_candidate") && (input.resultItems?.length ?? 0) === 0) {
-        // Terminal empty result: a later explicit human request starts a new flow.
-    }
-    else if (needsHumanSelection(execution, resultItem)) {
-        nextActions.push({
-            id: "select_result_item",
-            label: "Ask the human to select a result item, then submit the selection",
-            command: `itpay services action ${execution.service_execution_id} --action select_candidate --actor-type human --status approved --candidate <rank>`,
-            requires_human: true,
-            reason: "Do not choose a candidate without explicit human confirmation.",
-        });
-    }
-    else if (prePurchase) {
-        const action = {
-            id: "invoke_capability",
-            label: `Invoke ${prePurchase.capability_id}`,
-            command: `itpay services invoke ${execution.service_execution_id} --capability ${prePurchase.capability_id} --input key=value --json`,
-        };
-        if (prePurchase.free_quota_limit) {
-            action.reason = `One keyword per execution. Free quota limit: ${prePurchase.free_quota_limit} per ${prePurchase.quota_subject || "subject"}.`;
-        }
-        nextActions.push(action);
-    }
-    else {
-        nextActions.push({
-            id: "inspect_service_execution",
-            label: "Read Service Execution state",
-            command: `itpay services next ${execution.service_execution_id} --json`,
-        });
-    }
-    return {
-        kind: "service_execution",
-        summary: `service execution ${execution.service_execution_id}: ${execution.status}/${execution.phase}${input.effectiveQuota ? `, quota ${input.effectiveQuota.remaining}/${input.effectiveQuota.limit}` : ""}`,
-        state: {
-            service_execution_id: execution.service_execution_id,
-            service_id: execution.service_id,
-            status: execution.status,
-            phase: execution.phase,
-            current_capability_id: execution.current_capability_id,
-            checkout_required: execution.checkout_required,
-            next_action: execution.next_action,
-            delivery: delivery
-                ? {
-                    status: delivery.status,
-                    delivery_mode: deliveryMode || undefined,
-                    vault_artifact_id: delivery.vault_artifact_id,
-                    vault_status: delivery.vault_status,
-                    vault_payload_state: delivery.vault_payload_state,
-                    reveal_status: delivery.reveal_status,
-                    grant_status: delivery.grant_status ?? "missing",
-                    grant_expires_at: delivery.grant_expires_at,
-                }
-                : undefined,
-            capabilities: capabilities.map((capability) => ({
-                capability_id: capability.capability_id,
-                agent_visible: capability.agent_visible,
-                requires_payment: capability.requires_payment,
-                vault_required: capability.vault_required,
-                delivery_email_required: capability.delivery_email_required,
-                delivery_email_purpose: capability.delivery_email_purpose,
-                price_amount_minor: capability.price_amount_minor,
-                price_currency: capability.price_currency,
-                free_quota_limit: capability.free_quota_limit,
-            })),
-            result_items: (input.resultItems ?? []).map((item) => ({
-                result_item_id: item.service_capability_result_item_id,
-                rank: item.rank,
-                display_title: item.display_title,
-                safe_payload: item.safe_payload,
-            })),
-            effective_quota: input.effectiveQuota,
-        },
-        next_actions: nextActions,
-        recovery,
-        ...(input.resultItems?.length
-            ? { visible_results: input.resultItems.map((item) => ({ rank: item.rank, title: item.display_title, safe_payload: item.safe_payload })) }
-            : {}),
-    };
-}
-function deliveryEmailGuidance(purpose) {
-    switch (purpose) {
-        case "receipt":
-            return "Ask the human for their email. It is used to send the order receipt; never invent or substitute an address.";
-        case "claim":
-            return "Ask the human for their email. It is used to send the protected result claim link; never invent or substitute an address.";
-        case "receipt_and_claim":
-            return "Ask the human for their email. It is used to send the order receipt and protected result claim link; never invent or substitute an address.";
-        default:
-            return "Ask the human for the required email and state only the Backend-declared purpose; never invent or substitute an address.";
-    }
-}
-function firstPrePurchaseCapability(capabilities) {
-    return capabilities.find((capability) => capability.agent_visible && !capability.requires_payment)
-        ?? capabilities.find((capability) => capability.agent_visible);
-}
-function firstPaidCapability(capabilities) {
-    return (capabilities.find((capability) => capability.requires_payment && capability.vault_required) ??
-        capabilities.find((capability) => capability.requires_payment));
-}
-function needsHumanSelection(execution, resultItem) {
-    if (execution.phase !== "pre_purchase")
-        return false;
-    return execution.next_action === "select_candidate" || execution.next_action === "human_action_required" || resultItem !== undefined;
-}
-function latestServiceLine(cart) {
-    return [...cart.items].reverse().find((item) => item.service_execution_id);
-}
-function lineID(line) {
-    return line.cart_item_id ?? line.line_item_id ?? line.checkout_item_id ?? "<unknown_line>";
-}