@itpay/cli 2.0.34 → 2.0.36

package/README.md

@@ -53,6 +53,7 @@ Normative per-command contracts: [CLI Command Reference](docs/cli-reference/inde
 | `claude-code-desktop` | `claude-code` |
 | `claude-code-cli` | `terminal` |
 | `workbuddy` | `plain-chat` |
+| `zcode` | `plain-chat` |
 | `kimi-code` | `terminal` |
 | `openclaw` | 必须显式提供 |
 

package/dist/src/client/backend.js

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

package/dist/src/commands/buy.js

@@ -17,7 +17,7 @@ import { localizeCardURL, normalizeCardLocale } from "../render/locale.js";
 import { buildAgentChatHandoff } from "../render/markdown.js";
 import { formatMoney } from "../render/output.js";
 import { CommandContractError, writeCommandEnvelope } from "./guidance.js";
-import { buildCheckoutHandoff, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
+import { buildCheckoutHandoff, isLinkOnlyBrowserAgent, shouldPrepareLocalCheckoutImage } from "./checkout_handoff.js";
 import { qualifyItPayCommand } from "../state/agent_type.js";
 export async function runBuy(backend, config, options) {
     const err = validateContext(options.host, options.target);
@@ -267,7 +267,7 @@ export function buildCheckoutQRPlan(input) {
         host: input.host,
         summary,
         url: input.qrPayload,
-        ...(input.agentType?.trim().toLowerCase() === "workbuddy" && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
+        ...(isLinkOnlyBrowserAgent(input.agentType, platformKeyForHost(input.host)) && input.cardURL ? { linkOnlyURL: input.cardURL } : {}),
         preferredQRSources: [input.qrPNGURL ?? input.qrPayload],
         checkoutID: input.checkoutID,
         platform,

package/dist/src/commands/checkout_handoff.js

@@ -5,6 +5,12 @@ export function shouldPrepareLocalCheckoutImage(platform) {
 export function isWorkBuddyPlainChat(agentType, platform) {
     return agentType?.trim().toLowerCase() === "workbuddy" && platform === "plain_chat";
 }
+export function isZCodePlainChat(agentType, platform) {
+    return agentType?.trim().toLowerCase() === "zcode" && platform === "plain_chat";
+}
+export function isLinkOnlyBrowserAgent(agentType, platform) {
+    return isWorkBuddyPlainChat(agentType, platform) || isZCodePlainChat(agentType, platform);
+}
 export function buildWorkBuddyPresentFilesAction(url) {
     return {
         tool: "present_files",
@@ -23,7 +29,7 @@ export function buildCheckoutHandoff(input) {
         if (input.markdown)
             handoff.markdown = input.markdown;
     }
-    else if (input.platform === "plain_chat" && input.qrImageURL && !workBuddyAction) {
+    else if (input.platform === "plain_chat" && input.qrImageURL && !isLinkOnlyBrowserAgent(input.agentType, input.platform)) {
         handoff.qr_image_url = input.qrImageURL;
     }
     else if (input.platform === "telegram" && input.qrImageURL) {
@@ -41,6 +47,9 @@ function checkoutHandoffInstruction(agentType, platform, amount) {
     if (isWorkBuddyPlainChat(agentType, platform)) {
         return `Backend 尚未确认付款。立即严格按 handoff.agent_action.tool 和 handoff.agent_action.arguments 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount}，然后停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要下载或重建二维码，不要调用 pay，不要创建新 Checkout、Payment Intent 或 Execution。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }
+    if (isZCodePlainChat(agentType, platform)) {
+        return `Backend 尚未确认付款。立即用 ZCode 内置浏览器打开 handoff.url，让用户完成付款；确认已发起打开后说明金额 ${amount}，然后停止等待。不要只粘贴文字链接，不要下载、解析或重建二维码，不要创建新 Checkout、Payment Intent 或 Execution。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
+    }
     if (platform === "markdown") {
         return `Backend 尚未确认付款。把 handoff.markdown 原样发送到当前桌面对话，确认二维码、付款链接和金额 ${amount} 均已实际对用户可见，然后停止等待。不要创建新 Checkout、Payment Intent 或 Execution；只有用户明确表示已付款或要求查询状态时，才执行 next.command；用户的话不是付款成功证明。`;
     }

package/dist/src/commands/feedback.js

@@ -9,8 +9,8 @@ export async function runFeedbackSubmit(backend, orderID, options) {
     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);
+    const context = await backend.getServiceFeedbackOptions(normalizedOrderID);
+    const choices = feedbackItemChoices(context);
     if (choices.length === 0) {
         throw new CommandContractError("feedback_unavailable", "this order has no service item available for feedback", "告诉用户这笔订单当前没有可评价的服务项目并停止；不要猜测项目 ID、切换身份或创建其他反馈。", []);
     }
@@ -18,10 +18,10 @@ export async function runFeedbackSubmit(backend, orderID, options) {
         writeCommandEnvelope({
             status: "feedback_item_selection_required",
             result: {
-                ...(order.order_code ? { order_code: order.order_code } : {}),
+                ...(context.order_code ? { order_code: context.order_code } : {}),
                 items: choices.map(({ rank, title, subject }) => ({ rank, title, ...(subject ? { subject } : {}) })),
             },
-            instruction: "用服务名称和主题让用户选择要评价哪一项；不要展示内部 ID。用户选择后，Agent 使用同一订单、评分和留言并加入所选 item rank 自己执行提交。",
+            instruction: "用服务名称和主题让用户选择要复盘哪一项；不要展示内部 ID。用户选择后，Agent 使用同一订单、已有评分或留言（如有）并加入所选 item rank 自己执行提交。",
             next: null,
             recovery: [],
         }, outputOptions(options));
@@ -33,9 +33,23 @@ export async function runFeedbackSubmit(backend, orderID, options) {
     if (!choice) {
         throw new CommandContractError("feedback_item_invalid", `item rank ${itemRank} is not available for feedback`, "只使用当前订单返回的服务项目编号；不要猜测内部 ID。本次未提交反馈。", []);
     }
+    if (rating === undefined && !userNote && choice.item.agent_feedback_submitted) {
+        writeCommandEnvelope({
+            status: "feedback_already_submitted",
+            result: {
+                ...(context.order_code ? { order_code: context.order_code } : {}),
+                service_title: choice.title,
+            },
+            instruction: "这笔服务的安全复盘已经记录；无需再次提交或打扰用户，停止。用户以后明确补充评分或评论时才更新。",
+            next: null,
+            recovery: [],
+        }, outputOptions(options));
+        return;
+    }
     const note = formatFeedbackNote({
         userNote,
-        outcome: order.status,
+        hasRating: rating !== undefined,
+        outcome: context.status,
         serviceTitle: choice.title,
         environment: options.environment,
         ...(options.agentType ? { agentType: options.agentType } : {}),
@@ -45,24 +59,28 @@ export async function runFeedbackSubmit(backend, orderID, options) {
     }
     const response = await backend.submitServiceFeedback(normalizedOrderID, {
         order_item_id: choice.item.order_item_id,
-        rating,
+        ...(rating !== undefined ? { rating } : {}),
         note,
     });
     writeCommandEnvelope({
         status: "feedback_submitted",
         result: {
-            ...(order.order_code ? { order_code: order.order_code } : {}),
+            ...(context.order_code ? { order_code: context.order_code } : {}),
             service_title: choice.title,
-            rating: response.feedback.rating,
+            ...(response.feedback.rating !== undefined ? { rating: response.feedback.rating } : {}),
             feedback_status: response.feedback.status,
         },
-        instruction: "告诉用户反馈已经记录并表示感谢，然后停止。不要承诺回复、处理时间、退款或结果变更。",
+        instruction: rating !== undefined || userNote
+            ? "告诉用户反馈已经记录并表示感谢，然后停止。不要承诺回复、处理时间、退款或结果变更。"
+            : "服务复盘已经记录；无需打扰用户，停止。不要声称用户给了评分或评论。",
         next: null,
         recovery: [],
     }, outputOptions(options));
 }
 export function normalizeFeedbackRating(value) {
     const normalized = value?.trim().toLowerCase() ?? "";
+    if (!normalized)
+        return undefined;
     const numeric = normalized.match(/^([1-5])(?:\s*(?:\/\s*5|分|星|stars?))?$/u);
     if (numeric)
         return Number(numeric[1]);
@@ -84,11 +102,11 @@ function normalizeItemRank(value) {
     }
     return rank;
 }
-function feedbackItemChoices(order) {
-    return order.items.flatMap((item, index) => {
+function feedbackItemChoices(context) {
+    return context.items.flatMap((item, index) => {
         if (!item.order_item_id?.trim())
             return [];
-        const subject = feedbackSubject(item);
+        const subject = safeLine(item.subject ?? "").slice(0, 160);
         return [{
                 rank: index + 1,
                 item,
@@ -97,17 +115,6 @@ function feedbackItemChoices(order) {
             }];
     });
 }
-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")
@@ -120,7 +127,8 @@ function formatFeedbackNote(input) {
         ? `## Summary\n${input.userNote.split("\n").map((line) => `> ${line}`).join("\n")}\n\n`
         : "";
     return `${summary}## Context\n` + [
-        "- Source: user-confirmed via agent",
+        "- Source: agent-postmortem",
+        `- Human input: ${humanInputSummary(input.hasRating, Boolean(input.userNote))}`,
         `- Outcome: ${safeLine(input.outcome) || "unknown"}`,
         `- Service: ${safeLine(input.serviceTitle) || "未命名服务"}`,
         `- Client: @itpay/cli ${CLI_VERSION}`,
@@ -128,6 +136,15 @@ function formatFeedbackNote(input) {
         `- Environment: ${input.environment}`,
     ].join("\n");
 }
+function humanInputSummary(hasRating, hasComment) {
+    if (hasRating && hasComment)
+        return "rating and comment included";
+    if (hasRating)
+        return "rating included";
+    if (hasComment)
+        return "comment included";
+    return "not provided";
+}
 function safeLine(value) {
     return value.replace(/[\r\n\u0000-\u001F\u007F]+/gu, " ").trim();
 }

package/dist/src/commands/guidance.js

@@ -5,10 +5,10 @@ import { qualifyBackendCommand } from "../state/config.js";
 export function isTerminalServiceExecutionStatus(status) {
     return status === "failed" || status === "refunded" || status === "cancelled";
 }
-export function appendOptionalFeedbackInvitation(instruction, outcome) {
+export function appendFeedbackPostmortemInstruction(instruction, outcome) {
     const invitation = outcome === "delivered"
-        ? "结果解释完毕后，可以询问用户是否愿意给这次服务 1–5 分和一句可选建议。只有用户明确评分后，Agent 才使用同一订单提交反馈；不要展示命令或内部 ID，同一对话最多询问一次。"
-        : "先完成同一订单的恢复和退款权利解释；处理清楚后，可以询问用户是否愿意给 1–5 分并说明卡壳点。只有用户明确评分后才提交反馈，同一对话最多询问一次。";
+        ? "结果解释完毕后，Agent 必须为同一订单提交一次安全服务复盘；用户评分和评论均可选，只在用户明确给出时忠实附上，不得猜分或上传对话、报告正文、联系方式和原始日志。"
+        : "先完成同一订单的恢复和退款权利解释；处理清楚后，Agent 必须为同一订单提交一次安全服务复盘。只附上用户明确表达的评分或卡壳点，不得猜测。";
     return `${instruction} ${invitation}`;
 }
 export class CommandContractError extends Error {

package/dist/src/commands/install.js

@@ -7,6 +7,7 @@ export const INSTALL_AGENT_TYPES = [
     "claude-code-desktop",
     "claude-code-cli",
     "workbuddy",
+    "zcode",
     "kimi-code",
     "openclaw",
 ];
@@ -16,6 +17,7 @@ const INSTRUCTIONS = {
     "claude-code-desktop": "在 Claude Code Desktop 中始终传这个 Agent Type；付款时把返回的二维码和链接实际展示到当前对话。",
     "claude-code-cli": "在 Claude Code CLI 中始终传这个 Agent Type；付款交接只应显示在用户可见终端。",
     workbuddy: "在 WorkBuddy 中始终传这个 Agent Type。运行会持久化 ~/.itpay-v3 的 ItPay Bash 命令前，把 Shell 工具参数 dangerouslyDisableSandbox 设为 true；用户拒绝权限时停止，不要切换 Node、删除 identity 或处理 lock。Checkout 返回已渲染的付款 Card Link 和 present_files action；原样执行一次 action 打开 handoff.url，不要检查本地二维码文件。",
+    zcode: "在 ZCode 中始终传这个 Agent Type。Checkout 或授权返回 handoff.url 后，立即用 ZCode 内置浏览器打开；不要只粘贴文字链接或重建二维码。只有内置浏览器不可用时才展示同一个可点击链接。",
     "kimi-code": "保持 kimi-code Agent Type，使用标准 CLI 命令和终端付款交接；不要切换到其他平台身份。",
     openclaw: "保持 openclaw Agent Type；每个展示命令都从当前可信会话上下文显式传 --host，IM 入口同时传 --target。Telegram 使用返回的原生 message action，其他入口展示标准二维码和付款链接。",
 };

package/dist/src/commands/order.js

@@ -1,5 +1,5 @@
 import { formatMoney } from "../render/output.js";
-import { appendOptionalFeedbackInvitation, writeCommandEnvelope } from "./guidance.js";
+import { appendFeedbackPostmortemInstruction, writeCommandEnvelope } from "./guidance.js";
 export async function runOrder(backend, orderID, options = {}) {
     const order = await backend.getOrder(orderID);
     const [delivery, refundResponse] = await Promise.all([
@@ -29,7 +29,7 @@ function orderEnvelope(order, delivery, lockedRefund) {
         next = { command: `itpay services next ${delivery.service_execution_id} --json`, reason: "读取交付状态" };
     }
     else if (order.status === "failed") {
-        instruction = appendOptionalFeedbackInvitation("先告诉用户这笔订单没有正常交付，不需要重复付款或重新下单；先检查原订单是否已有退款，再由用户决定是否申请。", "failed");
+        instruction = appendFeedbackPostmortemInstruction("先告诉用户这笔订单没有正常交付，不需要重复付款或重新下单；先检查原订单是否已有退款，再由用户决定是否申请。", "failed");
         next = { command: `itpay refund list --order ${order.order_id} --json`, reason: "检查同一订单的退款状态" };
     }
     else if (order.status === "refunded") {

package/dist/src/commands/pay.js

@@ -2,7 +2,7 @@
 // Checkout page; this command exists for controlled integration recovery.
 import { formatMoney } from "../render/output.js";
 import { writeCommandEnvelope } from "./guidance.js";
-import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat, isZCodePlainChat } from "./checkout_handoff.js";
 import { platformKeyForHost } from "../render/plan.js";
 export async function runPay(backend, options) {
     const intent = await backend.createPaymentIntent(options.checkoutID, {
@@ -20,12 +20,17 @@ function payEnvelope(intent, options) {
     const terminal = ["failed", "expired", "refunded"].includes(intent.status);
     const verified = intent.status === "verified" || intent.status === "partially_refunded";
     const handoff = {};
-    const workBuddyAction = isWorkBuddyPlainChat(options.agentType, platformKeyForHost(options.host));
-    if (!terminal && !verified && workBuddyAction) {
-        const url = intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
+    const platform = platformKeyForHost(options.host);
+    const workBuddyAction = isWorkBuddyPlainChat(options.agentType, platform);
+    const zcodeAction = isZCodePlainChat(options.agentType, platform);
+    if (!terminal && !verified && (workBuddyAction || zcodeAction)) {
+        const url = zcodeAction
+            ? intent.action?.qr_image_url ?? intent.action?.mobile_wallet_url
+            : intent.action?.mobile_wallet_url ?? intent.action?.qr_image_url;
         if (url) {
             handoff.url = url;
-            handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
+            if (workBuddyAction)
+                handoff.agent_action = buildWorkBuddyPresentFilesAction(url);
         }
     }
     else {
@@ -64,6 +69,9 @@ function payInstruction(options, verified, terminal, hasAction, amount) {
     if (isWorkBuddyPlainChat(options.agentType, platform)) {
         return `这是受控逃生入口。立即严格按 handoff.agent_action 原样执行一次，在右侧打开 handoff.url；确认工具调用成功后说明金额 ${amount} 并停止等待。若工具失败，只发送原始 handoff.url，报告未自动打开并停止。不要用 present_files 打开本地文件或二维码 PNG，不要立即查询、创建替代 Checkout 或 Payment Intent。`;
     }
+    if (isZCodePlainChat(options.agentType, platform)) {
+        return `这是受控逃生入口。立即用 ZCode 内置浏览器打开 handoff.url；确认已发起打开后说明金额 ${amount} 并停止等待。不要只粘贴文字链接，不要下载或重建二维码，不要立即查询、创建替代 Checkout 或 Payment Intent。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。`;
+    }
     if (options.host === "codex" || options.host === "claude-code")
         return "这是受控逃生入口；把 handoff 中的二维码或钱包链接实际发到当前桌面对话，然后停止等待。";
     if (options.host === "terminal")

package/dist/src/commands/services.js

@@ -8,7 +8,7 @@ import { buildAgentChatHandoff } from "../render/markdown.js";
 import { platformKeyForHost } from "../render/plan.js";
 import { renderTerminalQR } from "../render/qr.js";
 import { buildCheckoutQRPlan } from "./buy.js";
-import { appendOptionalFeedbackInvitation, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
+import { appendFeedbackPostmortemInstruction, CommandContractError, isTerminalServiceExecutionStatus, writeCommandEnvelope, } from "./guidance.js";
 const serviceActionStatuses = new Set(["pending", "approved", "rejected", "expired", "cancelled"]);
 export async function runServicesStart(backend, serviceID, options = {}) {
     const host = options.host ?? "terminal";
@@ -678,7 +678,7 @@ function servicesNextEnvelope(model) {
             instruction: execution.status === "refunded"
                 ? "告诉用户这笔服务已经退款并永久结束。Agent 不重放服务步骤、不创建付款页面或尝试读取旧交付。"
                 : paidFailure
-                    ? appendOptionalFeedbackInvitation("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
+                    ? appendFeedbackPostmortemInstruction("告诉用户：付款和订单已经记录，但本次服务没有正常完成，不需要再次付款或重新下单。然后从同一订单检查退款状态；Agent 不重放服务步骤、创建付款页面或再次调用数据来源，也不把技术故障归咎于用户。", "failed")
                     : "告诉用户本次服务已经结束且没有可继续的交付。Agent 不重放服务步骤或创建付款页面。",
             next: null,
             recovery: [
@@ -744,7 +744,7 @@ function servicesNextEnvelope(model) {
                 items,
             },
             instruction: delivery?.order_id
-                ? appendOptionalFeedbackInvitation(items.length > 0
+                ? appendFeedbackPostmortemInstruction(items.length > 0
                     ? selection
                         ? "搜索已完成。用编号、名称和可公开字段向用户说明结果，然后停止。只有用户明确选择候选并要求继续时才执行 next.command；不要提及 safe_payload。"
                         : "这一步的结果已经可用。用普通语言解释可公开字段并停止；不要提及 Graph、safe_payload 或内部 ID。"
@@ -887,7 +887,7 @@ function grantedResultEnvelope(response, orderID) {
             payload: response.result,
         },
         instruction: orderID
-            ? appendOptionalFeedbackInvitation("结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。", "delivered")
+            ? appendFeedbackPostmortemInstruction("结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。", "delivered")
             : "结果来自当前有效 Vault Grant；只使用本次授权字段，过期后停止读取并重新请求用户同意。",
         next: null,
         recovery: [],

package/dist/src/commands/vault_handoff.js

@@ -1,7 +1,7 @@
 import { platformKeyForHost } from "../render/plan.js";
 import { downloadBrandQRToTmp } from "../render/ide.js";
 import { renderTerminalQR } from "../render/qr.js";
-import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat } from "./checkout_handoff.js";
+import { buildWorkBuddyPresentFilesAction, isWorkBuddyPlainChat, isZCodePlainChat } from "./checkout_handoff.js";
 const AUTH_ATTACH_REASON = "The human must be able to open or scan this official ItPay authorization handoff. " +
     "Render the local image in the current desktop chat; if that fails, show the unchanged official URL.";
 export async function buildVaultHandoff(input) {
@@ -14,6 +14,12 @@ export async function buildVaultHandoff(input) {
             instruction: "向用户说明这是查看已购内容的只读授权，然后严格按 handoff.agent_action 原样执行一次。打开成功后停止等待；失败时只发送同一个 handoff.url。用户完成后重新运行最初的读取命令，不要再次创建授权请求。",
         };
     }
+    if (isZCodePlainChat(input.agentType, platform)) {
+        return {
+            handoff,
+            instruction: "向用户说明这是查看已购内容的只读授权，然后立即用 ZCode 内置浏览器打开 handoff.url。确认已发起打开后停止等待；不要只粘贴文字链接，也不要下载或重建二维码。只有内置浏览器明确不可用时，才展示同一个可点击 handoff.url。用户完成后重新运行最初的读取命令，不要再次创建授权请求。",
+        };
+    }
     if (platform === "markdown") {
         const downloaded = input.imageAttachEnabled && input.qrPNGURL
             ? await downloadBrandQRToTmp(input.qrPNGURL, "auth", input.requestID, {

package/dist/src/main.js

@@ -43,7 +43,7 @@ Common human intents:
   Previously purchased item vault list
   Purchase history           orders
   Delivery or refund problem resume the known Order or Refund
-  Rate a purchased service   feedback submit
+  Review a completed service feedback submit
 
 The Agent runs commands. Ask the human only to choose, authorize, pay, provide
 required contact details, or confirm a refund. Never expose commands or internal IDs.
@@ -966,7 +966,7 @@ program
 const feedback = program.command("feedback").description("Rate one service item from an existing order");
 feedback
     .command("submit")
-    .description("Submit a human-confirmed rating and optional comment")
+    .description("Submit a safe Agent postmortem with optional human rating and comment")
     .option("--order <order_id>")
     .option("--rating <rating>")
     .option("--note <text>")

package/dist/src/state/client_context.js

@@ -62,6 +62,8 @@ export function defaultHostForAgentType(agentType) {
         return "claude-code";
     if (normalized === "workbuddy")
         return "plain-chat";
+    if (normalized === "zcode")
+        return "plain-chat";
     if (normalized === "openclaw")
         return undefined;
     return "terminal";

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 DEV_BASE_URL = "https://dev.itpay.ai";
-export const CLI_VERSION = "2.0.34";
-export const API_CONTRACT_REVISION = "sha256:95a6077248c820f92511ef6d41635881072ad399c18f347ee282253edb83e55f";
+export const CLI_VERSION = "2.0.36";
+export const API_CONTRACT_REVISION = "sha256:20986f3d7a770f9c696c0576f3ae4898f0d23a519bd489c1727382a16270fab2";
 const CART_SESSION_DEFAULT_DIR = ".itpay-v3";
 const CART_SESSION_FILENAME = "cart.json";
 const OPERATION_JOURNAL_FILENAME = "operations.json";

package/dist/src/state/operation_journal.js

@@ -1,80 +1,93 @@
-import { chmodSync, closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname } from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, existsSync, linkSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
 export class OperationJournal {
-    path;
-    constructor(path) {
-        this.path = path;
+    legacyPath;
+    constructor(legacyPath) {
+        this.legacyPath = legacyPath;
     }
     async getOrCreate(operationKey) {
-        return withFileLock(`${this.path}.lock`, async () => {
-            const state = this.read();
-            const existing = state.operations[operationKey];
-            if (existing)
-                return existing.id;
-            const id = `op_${randomUUID().replaceAll("-", "")}`;
-            state.operations[operationKey] = { id, createdAt: new Date().toISOString() };
-            atomicOwnerOnlyWrite(this.path, JSON.stringify(state, null, 2));
-            return id;
-        });
-    }
-    read() {
-        if (existsSync(this.path)) {
+        const operationKeyHash = createHash("sha256").update(operationKey).digest("hex");
+        const recordDirectory = `${this.legacyPath}.d`;
+        const recordPath = resolve(recordDirectory, `${operationKeyHash}.json`);
+        const existing = readRecord(recordPath, operationKeyHash);
+        if (existing)
+            return existing.id;
+        mkdirSync(recordDirectory, { recursive: true, mode: 0o700 });
+        chmodSync(recordDirectory, 0o700);
+        const record = {
+            schemaVersion: "itpay.operation.v2",
+            operationKeyHash,
+            id: this.readLegacyID(operationKey) ?? `op_${randomUUID().replaceAll("-", "")}`,
+            createdAt: new Date().toISOString(),
+        };
+        const temporaryPath = resolve(recordDirectory, `.${basename(recordPath)}.${process.pid}.${randomUUID()}.tmp`);
+        try {
+            writeFileSync(temporaryPath, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx", mode: 0o600 });
+            chmodSync(temporaryPath, 0o600);
             try {
-                const parsed = JSON.parse(readFileSync(this.path, "utf8"));
-                if (parsed.schemaVersion === "itpay.operations.v1" && parsed.operations)
-                    return parsed;
+                linkSync(temporaryPath, recordPath);
+                chmodSync(recordPath, 0o600);
+                return record.id;
             }
-            catch {
-                // A malformed local cache is replaced; server facts remain authoritative.
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                const winner = readRecord(recordPath, operationKeyHash);
+                if (!winner)
+                    throw new Error("ItPay operation journal record disappeared during publication");
+                return winner.id;
             }
         }
-        return { schemaVersion: "itpay.operations.v1", operations: {} };
-    }
-}
-function atomicOwnerOnlyWrite(path, value) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temporary, value, { encoding: "utf8", mode: 0o600 });
-    chmodSync(temporary, 0o600);
-    renameSync(temporary, path);
-    chmodSync(path, 0o600);
-}
-async function withFileLock(path, run) {
-    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-    let descriptor;
-    for (let attempt = 0; attempt < 200; attempt += 1) {
-        try {
-            descriptor = openSync(path, "wx", 0o600);
-            break;
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
+        finally {
             try {
-                if (Date.now() - statSync(path).mtimeMs > 30_000)
-                    unlinkSync(path);
+                unlinkSync(temporaryPath);
             }
-            catch (statError) {
-                if (statError.code !== "ENOENT")
-                    throw statError;
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
             }
-            await new Promise((resolve) => setTimeout(resolve, 25));
         }
     }
-    if (descriptor === undefined)
-        throw new Error("timed out waiting for ItPay operation journal lock");
-    try {
-        return await run();
-    }
-    finally {
-        closeSync(descriptor);
+    readLegacyID(operationKey) {
+        if (!existsSync(this.legacyPath))
+            return undefined;
         try {
-            unlinkSync(path);
+            const parsed = JSON.parse(readFileSync(this.legacyPath, "utf8"));
+            if (parsed.schemaVersion !== "itpay.operations.v1" || !parsed.operations)
+                return undefined;
+            const id = parsed.operations[operationKey]?.id;
+            return typeof id === "string" && isOperationID(id) ? id : undefined;
         }
-        catch (error) {
-            if (error.code !== "ENOENT")
-                throw error;
+        catch {
+            return undefined;
         }
     }
 }
+function readRecord(path, expectedHash) {
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("ItPay operation journal record is invalid");
+    }
+    if (!isOperationRecord(parsed, expectedHash)) {
+        throw new Error("ItPay operation journal record is invalid");
+    }
+    return parsed;
+}
+function isOperationRecord(value, expectedHash) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schemaVersion === "itpay.operation.v2" &&
+        record.operationKeyHash === expectedHash &&
+        typeof record.id === "string" && isOperationID(record.id) &&
+        typeof record.createdAt === "string" && !Number.isNaN(Date.parse(record.createdAt));
+}
+function isOperationID(value) {
+    return /^op_[a-zA-Z0-9_-]+$/.test(value);
+}

package/docs/agent/buyer/identity-and-sessions.json

@@ -25,8 +25,9 @@
   ],
   "local_state_recovery": [
     "Device state updates use an atomic directory lock and owner-only atomic file replacement; no lock file is opened with fs.open or fs.openSync.",
+    "Operation idempotency uses one immutable owner-only record per operation key. Different commands and Agent processes do not share a global operation-journal lock; legacy operations.json is read only.",
     "On device_state_unwritable, use the reported operation and errno to diagnose the failing stage without exposing local paths; keep the same Agent Type and CLI/Node launcher, restore Host-approved persistent access to ~/.itpay-v3, then retry the original command.",
-    "Do not manually create a lock, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
+    "Do not manually create or delete state locks, switch Node runtimes, delete identity, or rotate Agent Type as a retry strategy."
   ],
   "commands": [
     {

package/docs/agent/buyer/install-and-setup.json

@@ -13,7 +13,7 @@
     {
       "intent": "list supported Agent Types",
       "command": "itpay install --json",
-      "success_signal": "status is install_targets and exactly seven supported Agent Type definitions are returned"
+      "success_signal": "status is install_targets and exactly eight supported Agent Type definitions are returned"
     },
     {
       "intent": "read setup for the real runtime",
@@ -38,7 +38,7 @@
     "Production defaults to https://app.itpay.ai. Testing may set ITPAY_BACKEND_URL to the exact official URL https://dev.itpay.ai; no other Backend is allowed.",
     "If backend_contract_incompatible includes result.required_cli_version, stop all ItPay business commands and use only the exact distribution-specific update recovery returned by the CLI; never replace its version with latest.",
     "After upgrading, require itpay --version to equal result.required_cli_version before running readyz again; never change Agent Type or Device identity to recover compatibility.",
-    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, kimi-code, or openclaw.",
+    "Use one exact type: codex-desktop, codex-cli, claude-code-desktop, claude-code-cli, workbuddy, zcode, kimi-code, or openclaw.",
     "For compatibility, a global --agent-type codex declaration is normalized immediately to codex-desktop; all registration, output, and returned commands use codex-desktop. Never generate the alias, and do not use codex as an install target.",
     "One local private key is reused, while Device registrations and quota lineage remain separate for app.itpay.ai and dev.itpay.ai.",
     "Within each official Backend registration, each Agent Type has one Agent Instance; all windows and chats of the same type reuse it.",
@@ -70,6 +70,7 @@
     "codex",
     "claude code",
     "workbuddy",
+    "zcode",
     "kimi code",
     "openclaw"
   ]

package/docs/agent/buyer/quickstart.json

@@ -25,7 +25,7 @@
     "previous_content": "Use vault list, optionally with the subject as --query.",
     "purchase_history": "Use orders.",
     "refund_or_paid_problem": "Resume the known Order or Refund before creating anything new.",
-    "service_feedback": "Finish the original order outcome first; after the human explicitly gives a 1-5 rating, use feedback submit.",
+    "service_feedback": "Finish the original order outcome first, then submit one safe Agent postmortem; include a rating or comment only when the human explicitly gives it.",
     "ambiguous": "Ask whether the human wants an earlier purchase or a new query before calling ItPay."
   },
   "commands": [{