@itpay/cli 2.0.3 → 2.0.7

package/dist/src/commands/checkout.js

@@ -1,97 +1,137 @@
-// Reads the canonical V3 checkout presentation. Requires both checkout_id
-// and the checkout-scoped display_token. Supports terminal and agent markdown.
-import { formatMoney } from "../render/output.js";
-import { hintFor } from "../render/status.js";
-import { resolveOutput } from "../render/sink.js";
-import { ensureIdeImageAttach, ideImageAttachBlock } from "../render/ide.js";
+// Reads one canonical Checkout presentation. This command never creates a
+// Checkout and only prepares a payment handoff while the Checkout is pending.
+import { ensureIdeImageAttach } from "../render/ide.js";
+import { buildAgentChatHandoff } from "../render/markdown.js";
+import { platformKeyForHost } from "../render/plan.js";
+import { renderTerminalQR } from "../render/qr.js";
 import { DEFAULT_BASE_URL } from "../state/config.js";
+import { buildCheckoutQRPlan } from "./buy.js";
+import { writeCommandEnvelope } from "./guidance.js";
 export async function runCheckoutPresentation(backend, options) {
-    const out = resolveOutput(options.output);
     const presentation = await backend.getCheckoutPresentation(options.checkoutID, options.displayToken);
+    const host = options.host ?? "terminal";
+    if (!checkoutNeedsHumanHandoff(presentation.checkout.status)) {
+        const envelope = terminalCheckoutEnvelope(presentation);
+        writeCommandEnvelope(envelope, {
+            ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+            ...(options.output ? { output: options.output } : {}),
+            plainResult: checkoutPlainResult(envelope.result),
+        });
+        return;
+    }
     const checkoutURL = checkoutPageURL(options.baseURL, options.checkoutID, options.displayToken);
-    const qrPNGURL = presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken);
-    const plan = {
-        kind: "checkout_qr",
-        host: (options.host ?? "terminal"),
-        summary: "checkout presentation",
-        url: checkoutURL,
-        preferredQRSources: [qrPNGURL],
-        platform: {
-            text: "checkout presentation",
-            links: [{ label: "打开付款页面", url: checkoutURL }],
-            buttons: [],
-            blocks: [],
-        },
-    };
+    const qrPNGURL = absolutePublicURL(options.baseURL, presentation.qr_png_url ?? checkoutQRPNGURL(options.baseURL, options.checkoutID, options.displayToken));
+    const nextCommand = `itpay checkout --id ${options.checkoutID} --token ${options.displayToken} --json`;
+    const plan = buildCheckoutQRPlan({
+        host,
+        checkoutID: options.checkoutID,
+        checkoutURL,
+        displayToken: options.displayToken,
+        qrPayload: checkoutURL,
+        qrPNGURL,
+        nextAction: presentation.checkout.next_action,
+        orderItems: presentation.items.map((item) => ({
+            title: item.title,
+            quantity: item.quantity,
+            amountMinor: item.amount_minor,
+            currency: item.currency,
+        })),
+        orderCurrency: presentation.checkout.currency,
+    });
     await ensureIdeImageAttach(plan, {
         ...(options.baseURL ? { baseURL: options.baseURL } : {}),
     });
-    if (options.host === "codex" || options.host === "claude-code" || options.host === "trae") {
-        out(renderCheckoutMarkdown(presentation, plan) + "\n");
-    }
-    else {
-        out(renderCheckoutText(presentation) + "\n");
-        if (plan.ideImageAttach) {
-            out(ideImageAttachBlock(plan.ideImageAttach).filter((l) => l.length > 0).join("\n") + "\n");
-        }
-        out(`hint: ${hintFor("checkout", presentation.checkout.status)}\n`);
+    const envelope = pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand);
+    const plainResult = checkoutPlainResult(envelope.result);
+    if (!options.jsonOutput && platformKeyForHost(host) === "terminal") {
+        plainResult.push("qr:", await renderTerminalQR(checkoutURL, "terminal"));
     }
+    writeCommandEnvelope(envelope, {
+        ...(options.jsonOutput !== undefined ? { jsonOutput: options.jsonOutput } : {}),
+        ...(options.output ? { output: options.output } : {}),
+        plainResult,
+    });
 }
-function renderCheckoutText(presentation) {
-    const lines = [];
-    const c = presentation.checkout;
-    lines.push(`checkout ${c.checkout_id}`);
-    lines.push(`  status:      ${c.status}`);
-    lines.push(`  next_action: ${c.next_action}`);
-    lines.push(`  amount:      ${formatMoney(c.amount_minor, c.currency)}`);
-    lines.push(`  buyer:       ${presentation.buyer_session.state}`);
-    if (presentation.items.length > 0) {
-        lines.push("  items:");
-        for (const item of presentation.items) {
-            lines.push(`    - ${item.title} × ${item.quantity} (${formatMoney(item.amount_minor, item.currency)})`);
-        }
+function pendingCheckoutEnvelope(presentation, checkoutURL, plan, nextCommand) {
+    const platform = platformKeyForHost(plan.host);
+    const handoff = { url: checkoutURL };
+    if (plan.ideImageAttach?.status === "downloaded" && plan.ideImageAttach.localPath) {
+        handoff.qr_local_path = plan.ideImageAttach.localPath;
     }
-    if (presentation.payment_intents.length > 0) {
-        lines.push("  payment_intents:");
-        for (const intent of presentation.payment_intents) {
-            lines.push(`    - ${intent.payment_intent_id} ${intent.status} (${intent.payment_method_type}, ${formatMoney(intent.amount_minor, intent.currency)})`);
-        }
+    if (platform === "markdown") {
+        handoff.markdown = buildAgentChatHandoff(plan).markdown;
     }
-    return lines.join("\n");
+    else if (platform === "plain_chat" && plan.preferredQRSources[0]) {
+        handoff.qr_image_url = plan.preferredQRSources[0];
+    }
+    const amount = formatMoney(presentation.checkout.amount_minor, presentation.checkout.currency);
+    return {
+        status: "human_checkout_required",
+        result: {
+            checkout_id: presentation.checkout.checkout_id,
+            payment: "pending",
+            amount,
+        },
+        handoff,
+        instruction: pendingInstruction(platform, amount),
+        next: { command: nextCommand, reason: "稍后只查询同一 Checkout" },
+        recovery: [],
+    };
 }
-function renderCheckoutMarkdown(presentation, plan) {
-    const c = presentation.checkout;
-    const lines = [];
-    lines.push(`## :mag: Checkout ${c.checkout_id}`);
-    lines.push("");
-    lines.push(`| 字段 | 值 |`);
-    lines.push(`|------|-----|`);
-    lines.push(`| 状态 | ${c.status} |`);
-    lines.push(`| 操作 | ${c.next_action} |`);
-    lines.push(`| 金额 | ${formatMoney(c.amount_minor, c.currency)} |`);
-    lines.push(`| 买家 | ${presentation.buyer_session.state} |`);
-    lines.push("");
-    if (presentation.items.length > 0) {
-        lines.push(`| 项目 | 数量 | 单价 |`);
-        lines.push(`|------|:----:|------|`);
-        for (const item of presentation.items) {
-            lines.push(`| ${item.title} | ${item.quantity} | ${formatMoney(item.amount_minor, item.currency)} |`);
-        }
-        lines.push("");
+function terminalCheckoutEnvelope(presentation) {
+    const checkout = presentation.checkout;
+    const serviceExecutionIDs = [...new Set(presentation.items.map((item) => item.service_execution_id).filter((id) => Boolean(id)))];
+    const payment = checkout.status === "refunded" ? "refunded"
+        : checkout.status === "payment_succeeded" || checkout.status === "completed" ? "verified"
+            : checkout.status;
+    const result = {
+        checkout_id: checkout.checkout_id,
+        payment,
+        ...(presentation.completed_order_id ? { order_id: presentation.completed_order_id } : {}),
+        ...(serviceExecutionIDs.length === 1 ? { service_execution_id: serviceExecutionIDs[0] } : {}),
+        ...(serviceExecutionIDs.length > 1 ? { service_execution_ids: serviceExecutionIDs } : {}),
+    };
+    let status = checkout.status;
+    let instruction = "Checkout 已结束；不要再次展示付款二维码。";
+    let next = null;
+    const recovery = [];
+    if (payment === "verified") {
+        status = "completed";
+        instruction = "Backend 已确认这笔付款。不要再次展示付款入口，不要调用 pay，不要创建新 Checkout 或 Execution。现在只执行 next.command，读取同一 Execution 的履约结果。";
+        next = serviceExecutionIDs.length === 1
+            ? { command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "读取同一笔已付款 Service Execution" }
+            : presentation.completed_order_id
+                ? { command: `itpay order ${presentation.completed_order_id}`, reason: "读取已创建订单" }
+                : { command: "itpay orders", reason: "恢复已付款订单" };
     }
-    if (presentation.payment_intents.length > 0) {
-        lines.push(`### :credit_card: 支付`);
-        lines.push("");
-        for (const intent of presentation.payment_intents) {
-            lines.push(`- \`${intent.payment_intent_id}\` — ${intent.payment_method_type} — ${intent.status} — ${formatMoney(intent.amount_minor, intent.currency)}`);
-        }
-        lines.push("");
+    else if (checkout.status === "refunded") {
+        instruction = "该 Checkout 已退款，不要再次付款或展示二维码。";
+        if (presentation.completed_order_id)
+            next = { command: `itpay order ${presentation.completed_order_id}`, reason: "读取订单与退款状态" };
     }
-    if (plan.ideImageAttach) {
-        lines.push(...ideImageAttachBlock(plan.ideImageAttach));
+    else if (checkout.status === "failed" || checkout.status === "expired") {
+        instruction = "该 Checkout 已失效；不要继续使用当前付款入口。";
+        if (serviceExecutionIDs.length === 1) {
+            recovery.push({ command: `itpay services next ${serviceExecutionIDs[0]} --json`, reason: "由服务端决定是否可恢复 Checkout" });
+        }
     }
-    lines.push(`> :bulb: ${hintFor("checkout", c.status)}`);
-    return lines.join("\n");
+    return { status, result, instruction, next, recovery };
+}
+function checkoutNeedsHumanHandoff(status) {
+    return !new Set(["payment_succeeded", "completed", "failed", "expired", "refunded"]).has(status);
+}
+function checkoutPlainResult(result) {
+    return Object.entries(result).map(([key, value]) => `${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+}
+function pendingInstruction(platform, amount) {
+    if (platform === "markdown")
+        return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、链接和金额 ${amount} 已对用户可见，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
+    if (platform === "terminal")
+        return `Backend 尚未确认付款。在用户可见终端展示当前同一 Checkout 的二维码、链接和金额 ${amount}，然后停止等待。不要创建新 Checkout、Execution 或 Payment Intent；稍后仍然只执行 next.command 查询这一笔 Checkout。`;
+    return `Backend 尚未确认付款。把 handoff.url 作为可点击链接发送给用户，优先把 handoff.qr_local_path 作为图片附件发送，不能发送本地附件时使用 handoff.qr_image_url，并说明金额 ${amount}，然后停止等待。不要声称付款成功，不要创建新 Checkout、Execution 或 Payment Intent。稍后仍然只执行 next.command 查询这一笔 Checkout。`;
+}
+function formatMoney(amountMinor, currency) {
+    return `${(amountMinor / 100).toFixed(2)} ${currency}`;
 }
 function checkoutPageURL(baseURL, checkoutID, displayToken) {
     const root = publicRoot(baseURL);
@@ -104,3 +144,12 @@ function checkoutQRPNGURL(baseURL, checkoutID, displayToken) {
 function publicRoot(baseURL) {
     return (baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
 }
+function absolutePublicURL(baseURL, value) {
+    try {
+        const root = publicRoot(baseURL);
+        return new URL(value, `${root}/`).toString();
+    }
+    catch {
+        return value;
+    }
+}

package/dist/src/commands/docs.js

@@ -1,61 +1,107 @@
-import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-function findDocsDir() {
-    if (process.env.ITPAY_CLI_DOCS_DIR) {
-        return process.env.ITPAY_CLI_DOCS_DIR;
-    }
-    // dist/src/commands → ../../../docs/agent/buyer = <pkg>/docs/agent/buyer
-    const pkgPath = resolve(__dirname, "..", "..", "..", "docs", "agent", "buyer");
-    if (existsSync(pkgPath))
-        return pkgPath;
-    // src/commands → ../../docs/agent/buyer = <pkg>/docs/agent/buyer (dev mode)
-    const devPath = resolve(__dirname, "..", "..", "docs", "agent", "buyer");
-    if (existsSync(devPath))
-        return devPath;
-    return pkgPath;
-}
-const DOCS_DIR = findDocsDir();
-function loadDocs() {
-    const files = readdirSync(DOCS_DIR).filter((f) => f.endsWith(".json"));
-    return files.map((file) => {
-        const raw = readFileSync(resolve(DOCS_DIR, file), "utf-8");
-        return JSON.parse(raw);
+import { resolveOutput } from "../render/sink.js";
+import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
+const commandDir = dirname(fileURLToPath(import.meta.url));
+export function runDocsList(options = {}) {
+    const topics = loadDocs().map(({ topic, title, purpose }) => ({ topic, title, purpose }));
+    writeCommandEnvelope({
+        status: "listed",
+        result: { topics },
+        instruction: "选择与当前步骤最接近的一个 topic；不要一次加载全部文档。",
+        next: null,
+        recovery: [],
+    }, {
+        ...options,
+        plainResult: topics.flatMap((doc) => [`${doc.topic}: ${doc.title}`, `  ${doc.purpose}`]),
     });
 }
-export function runDocsList() {
-    const docs = loadDocs();
-    process.stdout.write(`Agent docs (${docs.length} topics):\n\n`);
-    for (const doc of docs) {
-        process.stdout.write(`  ${doc.topic}\n`);
-        process.stdout.write(`    title:   ${doc.title}\n`);
-        process.stdout.write(`    purpose: ${doc.purpose}\n\n`);
-    }
-}
-export function runDocsShow(topic) {
-    const docs = loadDocs();
-    const doc = docs.find((d) => d.topic === topic);
+export function runDocsShow(topic, options = {}) {
+    const normalized = topic.trim();
+    const doc = loadDocs().find((candidate) => candidate.topic === normalized);
     if (!doc) {
-        process.stderr.write(`doc topic "${topic}" not found. Use "itpay docs list" to see available topics.\n`);
-        process.exitCode = 1;
+        throw new CommandContractError("doc_not_found", `doc topic not found: ${topic}`, "使用稳定 topic 名称；不要根据标题猜 topic。", [
+            { command: "itpay docs list --json", reason: "列出全部 topic" },
+            { command: `itpay docs search ${shellWord(normalized || "topic")} --json`, reason: "按关键词重新搜索" },
+        ]);
+    }
+    const envelope = {
+        status: "shown",
+        result: { topic: doc.topic, content: doc },
+        instruction: "只执行文档中与当前服务端状态匹配的步骤；服务端返回的当前 next 优先。",
+        next: null,
+        recovery: [],
+    };
+    if (options.jsonOutput) {
+        writeCommandEnvelope(envelope, options);
         return;
     }
-    process.stdout.write(JSON.stringify(doc, null, 2) + "\n");
-}
-export function runDocsSearch(query) {
-    const docs = loadDocs();
-    const lower = query.toLowerCase();
-    const results = docs.filter((doc) => {
-        const text = [doc.topic, doc.title, doc.purpose, ...(doc.search_terms ?? [])].join(" ").toLowerCase();
-        return text.includes(lower);
-    });
-    if (results.length === 0) {
-        process.stdout.write(`no docs match "${query}"\n`);
+    const out = resolveOutput(options.output);
+    out("shown\n");
+    out(`${JSON.stringify(doc, null, 2)}\n`);
+    out(`instruction: ${envelope.instruction}\n`);
+}
+export function runDocsSearch(query, options = {}) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) {
+        throw new CommandContractError("docs_query_required", "docs search query must not be empty", "提供一个 topic、标题、用途或 search term 关键词。", [{ command: "itpay docs list --json", reason: "不确定关键词时列出 topic" }]);
+    }
+    const topics = loadDocs()
+        .filter((doc) => searchableText(doc).includes(normalized))
+        .map(({ topic, title, purpose }) => ({ topic, title, purpose }));
+    if (topics.length === 0) {
+        writeCommandEnvelope({
+            status: "no_match",
+            result: { query, topics: [] },
+            instruction: "没有匹配文档；缩短关键词，或列出全部 topic。",
+            next: { command: "itpay docs list --json", reason: "浏览稳定 topic" },
+            recovery: [],
+        }, options);
         return;
     }
-    process.stdout.write(`${results.length} matching docs:\n\n`);
-    for (const doc of results) {
-        process.stdout.write(`  ${doc.topic} — ${doc.title}\n`);
+    writeCommandEnvelope({
+        status: "matched",
+        result: { query, topics },
+        instruction: topics.length === 1
+            ? "已唯一匹配；读取该 topic。"
+            : "选择最相关的一个 topic；不要同时展开全部结果。",
+        next: topics.length === 1
+            ? { command: `itpay docs show ${topics[0].topic} --json`, reason: "读取唯一匹配文档" }
+            : null,
+        recovery: [],
+    }, {
+        ...options,
+        plainResult: topics.map((doc) => `${doc.topic}: ${doc.title}`),
+    });
+}
+function loadDocs() {
+    const docsDir = findDocsDir();
+    const files = readdirSync(docsDir).filter((file) => file.endsWith(".json")).sort();
+    return files.map((file) => parseDoc(readFileSync(resolve(docsDir, file), "utf8"), file))
+        .sort((left, right) => left.topic.localeCompare(right.topic));
+}
+function findDocsDir() {
+    if (process.env.ITPAY_CLI_DOCS_DIR)
+        return resolve(process.env.ITPAY_CLI_DOCS_DIR);
+    const packagePath = resolve(commandDir, "..", "..", "..", "docs", "agent", "buyer");
+    if (existsSync(packagePath))
+        return packagePath;
+    return resolve(commandDir, "..", "..", "docs", "agent", "buyer");
+}
+function parseDoc(raw, file) {
+    const value = JSON.parse(raw);
+    if (typeof value.schema_version !== "string" ||
+        typeof value.topic !== "string" ||
+        typeof value.title !== "string" ||
+        typeof value.purpose !== "string") {
+        throw new Error(`invalid agent doc: ${file}`);
     }
+    return value;
+}
+function searchableText(doc) {
+    return [doc.topic, doc.title, doc.purpose, ...(doc.search_terms ?? [])].join(" ").toLowerCase();
+}
+function shellWord(value) {
+    return /^[a-zA-Z0-9._-]+$/.test(value) ? value : JSON.stringify(value);
 }

package/dist/src/commands/guidance.js

@@ -1,5 +1,56 @@
 import { HttpError } from "../client/http.js";
 import { resolveOutput } from "../render/sink.js";
+import { declaredAgentType, qualifyItPayCommand } from "../state/agent_type.js";
+export function isTerminalServiceExecutionStatus(status) {
+    return status === "failed" || status === "refunded" || status === "cancelled";
+}
+export class CommandContractError extends Error {
+    code;
+    instruction;
+    recovery;
+    constructor(code, message, instruction, recovery) {
+        super(message);
+        this.code = code;
+        this.instruction = instruction;
+        this.recovery = recovery;
+        this.name = "CommandContractError";
+    }
+}
+export function writeCommandEnvelope(value, options = {}) {
+    const out = resolveOutput(options.output);
+    const agentType = options.agentType ?? declaredAgentType();
+    const qualified = qualifyEnvelope(value, agentType);
+    if (options.jsonOutput) {
+        out(JSON.stringify(qualified, null, 2) + "\n");
+        return;
+    }
+    out(`${qualified.status}\n`);
+    const facts = "result" in qualified ? qualified.result : qualified.error;
+    if (options.plainResult) {
+        for (const line of options.plainResult)
+            out(`${line}\n`);
+    }
+    else {
+        for (const [key, fact] of Object.entries(facts)) {
+            out(`${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+        }
+    }
+    if ("handoff" in qualified && qualified.handoff) {
+        for (const [key, fact] of Object.entries(qualified.handoff)) {
+            out(`handoff.${key}: ${typeof fact === "string" ? fact : JSON.stringify(fact)}\n`);
+        }
+    }
+    out(`instruction: ${qualified.instruction}\n`);
+    if (qualified.next)
+        out(`next: ${qualified.next.command}\n`);
+    if (qualified.recovery.length > 0) {
+        out("recovery:\n");
+        for (const action of qualified.recovery) {
+            out(`  - ${action.command}\n`);
+            out(`    reason: ${action.reason}\n`);
+        }
+    }
+}
 export function attachAgentGuidance(payload, guidance) {
     return {
         ...payload,
@@ -8,11 +59,18 @@ export function attachAgentGuidance(payload, guidance) {
 }
 export function printAgentGuidance(guidance, output) {
     const out = resolveOutput(output);
+    const agentType = declaredAgentType();
     out(`${guidance.summary}\n`);
     if (guidance.visible_results?.length) {
         out("results:\n");
-        for (const item of guidance.visible_results)
+        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");
@@ -21,7 +79,7 @@ export function printAgentGuidance(guidance, output) {
         out("next actions:\n");
         for (const action of guidance.next_actions) {
             out(`  - ${action.label}\n`);
-            out(`    ${action.command}\n`);
+            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
             if (action.requires_human)
                 out("    requires human confirmation\n");
             if (action.reason)
@@ -32,10 +90,20 @@ export function printAgentGuidance(guidance, output) {
         out("recovery:\n");
         for (const action of guidance.recovery) {
             out(`  - ${action.label}\n`);
-            out(`    ${action.command}\n`);
+            out(`    ${qualifyItPayCommand(action.command, agentType)}\n`);
         }
     }
 }
+function qualifyEnvelope(value, agentType) {
+    return {
+        ...value,
+        next: value.next ? { ...value.next, command: qualifyItPayCommand(value.next.command, agentType) } : null,
+        recovery: value.recovery.map((action) => ({
+            ...action,
+            command: qualifyItPayCommand(action.command, agentType),
+        })),
+    };
+}
 export function buildCartGuidance(cart, serviceModel) {
     const serviceLine = latestServiceLine(cart);
     if (serviceLine?.service_execution_id) {
@@ -126,7 +194,6 @@ export function buildServiceActionGuidance(action) {
             action_type: action.action_type,
             status: action.status,
             result_item_id: action.result_item_id,
-            selected_candidate_hash: action.selected_candidate_hash,
         },
         next_actions: [
             {
@@ -175,9 +242,19 @@ export function errorRecoveryActions(error) {
     if (error.code === "agent_identity_required") {
         return [
             {
-                id: "set_agent_identity",
-                label: "Set a stable agent device id",
-                command: "export ITPAY_AGENT_DEVICE_ID=<stable_agent_device_id>",
+                id: "inspect_agent_setup",
+                label: "Inspect supported Agent Type setup",
+                command: "itpay install --json",
+            },
+        ];
+    }
+    if (error.code === "agent_device_session_required") {
+        return [
+            {
+                id: "read_agent_session_rules",
+                label: "Read identity and session recovery rules",
+                command: "itpay skill show itpay-buyer --json",
+                reason: "The CLI already attempted one automatic session renewal; do not rotate identity or loop retries.",
             },
         ];
     }
@@ -253,6 +330,7 @@ function buildServiceGuidance(input) {
     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 = [
@@ -262,7 +340,18 @@ function buildServiceGuidance(input) {
             command: `itpay services get ${execution.service_execution_id}`,
         },
     ];
-    if (execution.status === "completed" || execution.next_action === "completed") {
+    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",
@@ -327,13 +416,13 @@ function buildServiceGuidance(input) {
             });
         }
     }
-    else if (input.providerCalled && (input.resultItems?.length ?? 0) === 0) {
+    else if ((input.providerCalled || execution.next_action === "select_candidate") && (input.resultItems?.length ?? 0) === 0) {
         nextActions.push({
-            id: "refine_search",
-            label: "Ask for a more specific company name before another lookup",
-            command: `itpay services invoke ${execution.service_execution_id} --capability ${execution.current_capability_id ?? "<capability_id>"} --input keyword=<more_specific_company_name>`,
+            id: "start_refined_search",
+            label: "Start a new execution with a more specific company name",
+            command: `itpay services start ${execution.service_id}`,
             requires_human: true,
-            reason: "The provider returned no candidates. Do not repeat the same query.",
+            reason: "No candidates were found. This execution is finished; use one new execution per new keyword.",
         });
     }
     else if (needsHumanSelection(execution, resultItem)) {
@@ -344,6 +433,12 @@ function buildServiceGuidance(input) {
             requires_human: true,
             reason: "Do not choose a candidate without explicit human confirmation.",
         });
+        nextActions.push({
+            id: "start_another_search",
+            label: "Search another company in a new execution",
+            command: `itpay services start ${execution.service_id}`,
+            reason: "This execution has completed its one keyword lookup; do not reuse it for another keyword.",
+        });
     }
     else if (prePurchase) {
         const action = {
@@ -352,7 +447,7 @@ function buildServiceGuidance(input) {
             command: `itpay services invoke ${execution.service_execution_id} --capability ${prePurchase.capability_id} --input key=value --json`,
         };
         if (prePurchase.free_quota_limit) {
-            action.reason = `Free quota limit: ${prePurchase.free_quota_limit} per ${prePurchase.quota_subject || "subject"}.`;
+            action.reason = `One keyword per execution. Free quota limit: ${prePurchase.free_quota_limit} per ${prePurchase.quota_subject || "subject"}.`;
         }
         nextActions.push(action);
     }
@@ -377,6 +472,7 @@ function buildServiceGuidance(input) {
             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,
@@ -397,16 +493,16 @@ function buildServiceGuidance(input) {
             })),
             result_items: (input.resultItems ?? []).map((item) => ({
                 result_item_id: item.service_capability_result_item_id,
-                stable_hash: item.stable_hash,
                 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 })) }
+            ? { visible_results: input.resultItems.map((item) => ({ rank: item.rank, title: item.display_title, safe_payload: item.safe_payload })) }
             : {}),
     };
 }