@harrylabsj/kiwi 0.8.0 → 0.10.0

package/dist/merchant-core/commands.js

@@ -0,0 +1,179 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { contentHash, executeApprovedCandidate, WriteApprovalCandidateError, } from "../agent/merchant/action-candidate.js";
+import { routeWriteCandidate } from "../agent/write-gate.js";
+import { MerchantWorkbenchError } from "../merchant/workbench-service.js";
+export class MerchantCommandLog {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 登记写命令（prepare）：校验工具已注册 → 执行器重读前置版本 → 写门
+     * force_pending 产候选（任何模式都不自动执行）。
+     */
+    async prepare(input) {
+        const executor = this.deps.executors.get(input.tool);
+        if (executor === undefined) {
+            throw new MerchantWorkbenchError("validation", `未注册的写工具 ${input.tool}（固定执行器注册表，禁止动态分发）`);
+        }
+        const preconditions = await executor.readPreconditions(input.arguments);
+        const args = { ...input.arguments, reason: input.reason ?? "" };
+        const outcome = await routeWriteCandidate({
+            mode: this.deps.mode,
+            approvals: this.deps.store,
+            profile: this.deps.profile,
+            now: this.deps.now,
+        }, {
+            tool: input.tool,
+            arguments: args,
+            preconditions,
+            risk: "write_catalog",
+            // 命令一律 pending：确认通道批准后才执行（任何模式都不自动执行）。
+            force_pending: true,
+            execute: (approvedArgs) => executor.execute(approvedArgs, this.deps.executorContext),
+            readPreconditions: () => executor.readPreconditions(input.arguments),
+        });
+        const candidate = "candidate" in outcome ? outcome.candidate : undefined;
+        if (candidate === undefined) {
+            throw new MerchantWorkbenchError("unavailable", "写门未产生候选");
+        }
+        return {
+            candidate,
+            preview: {
+                tool: input.tool,
+                arguments: args,
+                before: preconditions,
+                note: "展示预览 ≠ 批准；批准 ≠ 执行成功（执行前重校验前置版本与硬策略）。",
+            },
+            outcome,
+        };
+    }
+    /**
+     * 批准并执行（确认通道；管理页面调用）。
+     * 授权主体一致性：调用主体必须等于命令记录主体（store 按 principal 绑定）。
+     * 配置了确认凭证存储时，必须携带与该候选内容/主体/动作匹配的一次性凭证。
+     */
+    async executeApproved(commandId, callerPrincipalId, confirmationToken) {
+        if (callerPrincipalId !== this.deps.principalId) {
+            throw new MerchantWorkbenchError("auth", "批准主体与命令记录主体不一致（跨主体批准拒绝）");
+        }
+        try {
+            const candidate = this.deps.store.get(commandId);
+            if (candidate === undefined) {
+                throw new MerchantWorkbenchError("not_found", `未知命令 ${commandId}`);
+            }
+            const executor = this.deps.executors.get(candidate.tool);
+            if (executor === undefined) {
+                // 未注册工具的命令不可执行——fail-closed 失效。
+                this.deps.store.expireCandidate(commandId);
+                throw new MerchantWorkbenchError("validation", `命令 ${commandId} 的工具 ${candidate.tool} 未注册，已失效`);
+            }
+            // BUG-02：可信确认记录逐项核对（候选内容摘要/主体/商家/动作/有效期/单次）。
+            // 审查 P2：核销放在候选存在性/可执行性核对**之后**——候选已死时点击
+            // 批准不再白烧一次性凭证。
+            if (this.deps.confirmations !== undefined) {
+                const confirmation = this.deps.confirmations.consumeConfirmation(confirmationToken ?? "", {
+                    candidateId: commandId,
+                    candidateDigest: contentHash({
+                        arguments: candidate.arguments,
+                        preconditions: candidate.preconditions,
+                    }),
+                    principalId: callerPrincipalId,
+                    merchantId: this.deps.profile.owner_id,
+                    action: "approve",
+                });
+                if (confirmation === undefined) {
+                    throw new MerchantWorkbenchError("validation", "确认凭证无效/已使用/已过期或不匹配——没有可信用户确认记录时写操作不可执行");
+                }
+            }
+            this.deps.store.markApproved(commandId); // 过期/非 pending → 抛错（fail-closed）
+            const outcome = await executeApprovedCandidate(this.deps.store, commandId, {
+                readPreconditions: () => executor.readPreconditions(candidate.arguments),
+                execute: async (approvedArgs) => {
+                    const output = await executor.execute(approvedArgs, this.deps.executorContext);
+                    // 回读校验（写链路闭环）
+                    await executor.verifyAfter?.(approvedArgs, this.deps.executorContext);
+                    return output;
+                },
+            });
+            return outcome;
+        }
+        catch (err) {
+            if (err instanceof MerchantWorkbenchError)
+                throw err;
+            if (err instanceof WriteApprovalCandidateError) {
+                throw new MerchantWorkbenchError(err.code === "not_found" ? "not_found" : "validation", err.message);
+            }
+            throw new MerchantWorkbenchError("unavailable", err instanceof Error ? err.message : String(err));
+        }
+    }
+    /** 拒绝候选（确认通道；同样需确认凭证）。 */
+    async reject(commandId, callerPrincipalId, confirmationToken) {
+        if (callerPrincipalId !== this.deps.principalId) {
+            throw new MerchantWorkbenchError("auth", "拒绝主体与命令记录主体不一致");
+        }
+        const candidate = this.deps.store.get(commandId);
+        if (candidate === undefined) {
+            throw new MerchantWorkbenchError("not_found", `未知命令 ${commandId}`);
+        }
+        if (this.deps.confirmations !== undefined) {
+            const confirmation = this.deps.confirmations.consumeConfirmation(confirmationToken ?? "", {
+                candidateId: commandId,
+                candidateDigest: contentHash({
+                    arguments: candidate.arguments,
+                    preconditions: candidate.preconditions,
+                }),
+                principalId: callerPrincipalId,
+                merchantId: this.deps.profile.owner_id,
+                action: "reject",
+            });
+            if (confirmation === undefined) {
+                throw new MerchantWorkbenchError("validation", "确认凭证无效/已使用/已过期或不匹配（reject）");
+            }
+        }
+        return this.deps.store.reject(commandId);
+    }
+    /**
+     * 重启恢复：从命令记录恢复全部已注册工具的 pending 命令（钩子按存储
+     * 参数经注册表确定性重建）；未注册 tool 的命令 fail-closed 标 expired。
+     * 崩溃时停留在 executing 的候选一律 superseded（外部副作用不可判定，
+     * 绝不放行二次执行）。返回 { recovered, expiredUnknown, supersededExecuting }。
+     */
+    recoverPending() {
+        let recovered = 0;
+        let expiredUnknown = 0;
+        for (const candidate of this.deps.store.listPending()) {
+            if (this.deps.executors.has(candidate.tool)) {
+                recovered += 1; // 钩子由注册表在执行时按存储参数重建，无需进程内闭包
+            }
+            else {
+                this.deps.store.expireCandidate(candidate.candidate_id);
+                expiredUnknown += 1;
+            }
+        }
+        const supersededExecuting = this.deps.store.supersedeExecuting();
+        return { recovered, expiredUnknown, supersededExecuting };
+    }
+    listPending() {
+        return this.deps.store.listPending();
+    }
+    get(commandId) {
+        return this.deps.store.get(commandId);
+    }
+}
+export { WriteApprovalCandidateError };
+//# sourceMappingURL=commands.js.map

package/dist/merchant-core/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/merchant-core/commands.ts"],"names":[],"mappings":"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"}

package/dist/merchant-core/executor.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 固定执行器注册表（V2 阶段三：src/merchant-core/executor.ts）。
+ *
+ * 执行器按 tool 名**静态注册**（禁止动态/字符串拼接分发到任意函数）——
+ * 注册表在进程启动时一次建成，未知 tool 名 fail-closed。每个执行器提供：
+ *   - readPreconditions(args)：重读目标对象当前状态（前置版本/digest）；
+ *   - execute(args)：执行已批准参数（只执行命令记录里存储的参数）；
+ *   - verifyAfter?：执行后回读校验（写链路闭环的回读环节）。
+ *
+ * 恢复语义：进程重启后从命令记录（approval store）恢复 pending 时，钩子
+ * 由注册表按存储的 tool/arguments 确定性重建——不依赖任何进程内闭包。
+ */
+import type { MerchantClient } from "../agent/merchant/types.js";
+import type { AgentProfile, MerchantPolicy } from "../config/profile.js";
+import type { ApplyPolicyResult } from "./policy-runtime.js";
+import type { MerchantOperationStore } from "./operations.js";
+/** 执行器上下文（只读依赖 + 策略写接缝）。 */
+export interface ExecutorContext {
+    merchantClient: MerchantClient;
+    profile: AgentProfile;
+    /** 商家 owner_id（导入/撤回执行归属）。 */
+    ownerId: string;
+    /** 长任务 operation store（CSV 导入/撤回等；缺省时相关执行器 fail-closed）。 */
+    operations?: MerchantOperationStore;
+    /** 策略热更新写入（F17/BUG-07）：校验+原子写完整生效策略，返回版本/digest。 */
+    applyPolicyOverride?: ((patch: Record<string, unknown>) => Promise<ApplyPolicyResult>) | ((patch: Record<string, unknown>) => ApplyPolicyResult);
+    /** 运行中策略读取（BUG-07）：配置后硬策略（底价兜底）按当前生效策略执行，
+     *  不再固定用启动 profile 的 merchant_policy。 */
+    currentPolicy?: () => MerchantPolicy | undefined;
+    /** F14 两轨人工处理：shopping 轨 resolve（A2A 轨绝不进这里）。 */
+    resolveShoppingReview?: (input: {
+        conversation_id: string;
+        resolution: string;
+    }) => Promise<unknown>;
+}
+/** 固定执行器（一个 tool 一个）。 */
+export interface CommandExecutor {
+    readonly tool: string;
+    /** 重读目标对象前置状态（版本/digest 比对用）。 */
+    readPreconditions(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** 执行已批准参数。 */
+    execute(args: Record<string, unknown>, ctx: ExecutorContext): Promise<unknown>;
+    /** 执行后回读校验（可选；返回 false/抛错 = 回读不一致）。 */
+    verifyAfter?(args: Record<string, unknown>, ctx: ExecutorContext): Promise<void>;
+}
+export declare class MerchantExecutorRegistry {
+    private readonly registry;
+    private constructor();
+    /** 静态构造（固定白名单；新增写面必须显式加执行器）。 */
+    static buildDefault(ctx: ExecutorContext): MerchantExecutorRegistry;
+    get(tool: string): CommandExecutor | undefined;
+    has(tool: string): boolean;
+    tools(): string[];
+}

package/dist/merchant-core/executor.js

@@ -0,0 +1,218 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { parseProductCreateInput } from "../agent/merchant/types.js";
+import { publicProductView } from "../merchant/workbench-service.js";
+import { executeProductsImport } from "./product-import.js";
+export class MerchantExecutorRegistry {
+    registry = new Map();
+    constructor(executors) {
+        for (const e of executors)
+            this.registry.set(e.tool, e);
+    }
+    /** 静态构造（固定白名单；新增写面必须显式加执行器）。 */
+    static buildDefault(ctx) {
+        const productPreconditions = async (args) => {
+            const sku = String(args.sku ?? "");
+            return publicProductView(await ctx.merchantClient.getProduct(sku));
+        };
+        /** 硬策略强制（执行器层兜底）：价格变更不得低于私有底价（BUG-07：按
+         *  运行中生效策略校验，未配置运行中策略时回退启动 profile）。price 为
+         *  undefined = 本次变更不涉及价格（跳过）；非有限数值一律拒绝（审查 P1：
+         *  恒 false 比较会让底价检查纸面化）。 */
+        const enforceFloor = (price) => {
+            if (price === undefined)
+                return;
+            const floor = ctx.currentPolicy?.()?.min_unit_price_private ??
+                ctx.profile.merchant_policy?.min_unit_price_private;
+            if (floor === undefined)
+                return;
+            if (typeof price !== "number" || !Number.isFinite(price)) {
+                throw new Error("执行被硬策略拒绝：price 不是有限数值（不透出底价数值）");
+            }
+            if (price < floor) {
+                throw new Error("执行被硬策略拒绝：价格低于私有底价（不透出底价数值）");
+            }
+        };
+        return new MerchantExecutorRegistry([
+            // V1 草稿候选（内部 tool 名不变——写门/恢复机制的历史标识）
+            {
+                tool: "draft_product_change",
+                readPreconditions: productPreconditions,
+                execute: async (args, c) => {
+                    const changes = (args.changes ?? {});
+                    enforceFloor(typeof changes.price === "number" ? changes.price : undefined);
+                    return c.merchantClient.updateProduct(String(args.sku), changes);
+                },
+                verifyAfter: async (args, _c) => {
+                    await productPreconditions(args); // 回读可达性校验（§16 前置重哈希已比内容）
+                },
+            },
+            {
+                tool: "kiwi_merchant_prepare_product_create",
+                // 审查 P1：执行前白名单重校验并钉死 merchant_id 归属——prepare 层
+                // 已校验（service），这里防御 store 参数被篡改/迁移旧库缺校验。
+                readPreconditions: async (args) => {
+                    const product = (args.product ?? {});
+                    const sku = String(product.sku ?? "");
+                    // 已存在则旧授权失效（stale → superseded，见 executeApprovedCandidate）
+                    let exists = false;
+                    try {
+                        await ctx.merchantClient.getProduct(sku);
+                        exists = true;
+                    }
+                    catch {
+                        exists = false;
+                    }
+                    return { sku, exists };
+                },
+                execute: async (args, c) => {
+                    const product = parseProductCreateInput(args.product, c.ownerId);
+                    enforceFloor(product.price);
+                    return c.merchantClient.createProduct(product);
+                },
+            },
+            {
+                tool: "kiwi_merchant_prepare_product_update",
+                readPreconditions: productPreconditions,
+                execute: async (args, c) => {
+                    const changes = (args.changes ?? {});
+                    enforceFloor(typeof changes.price === "number" ? changes.price : undefined);
+                    return c.merchantClient.updateProduct(String(args.sku), changes);
+                },
+            },
+            {
+                tool: "kiwi_merchant_prepare_inventory_update",
+                readPreconditions: productPreconditions,
+                execute: async (args, c) => c.merchantClient.updateInventory(String(args.sku), Number(args.stock)),
+            },
+            {
+                // F08 语义落地：销售状态（paused flag）；上游 shopping-cli 2.x 无端点
+                // → client fail-closed 报「不可得」（不库存写零伪装下架）。
+                tool: "kiwi_merchant_prepare_listing_change",
+                readPreconditions: productPreconditions,
+                execute: async (args, c) => c.merchantClient.pauseListing(String(args.sku), args.paused === true),
+            },
+            {
+                // F14 两轨人工处理：executor 只接 shopping 轨（路由守卫在命令准备层）；
+                // A2A 轨人审由 A2A 侧机制处理，绝不进 shopping resolve。
+                tool: "kiwi_merchant_prepare_review_resolve",
+                readPreconditions: async (args) => ({
+                    source_id: String(args.source_id ?? ""),
+                }),
+                execute: async (args, c) => {
+                    if (c.resolveShoppingReview === undefined) {
+                        throw new Error("shopping 轨人工处理接口未配置（不可得）");
+                    }
+                    return c.resolveShoppingReview({
+                        conversation_id: String(args.source_id),
+                        resolution: String(args.resolution ?? ""),
+                    });
+                },
+            },
+            {
+                // F17 策略变更热更新（BUG-07）：执行器经共享策略提供器校验+原子写
+                // 完整生效策略，A2A/执行器按运行中策略立即生效；回执带版本/digest。
+                tool: "kiwi_merchant_prepare_policy_change",
+                readPreconditions: async () => ({ scope: "merchant_policy" }),
+                execute: async (args, c) => {
+                    if (c.applyPolicyOverride === undefined) {
+                        throw new Error("策略热更新接缝未配置（不可得）");
+                    }
+                    const patch = (args.patch ?? {});
+                    const result = await c.applyPolicyOverride(patch);
+                    return {
+                        applied: true,
+                        version: result.version,
+                        digest: result.digest,
+                        updated_at: result.updated_at,
+                        applied_keys: result.applied_keys,
+                    };
+                },
+            },
+            {
+                // F04 CSV 导入（长任务 + 幂等键 + 逐项回执）。
+                tool: "kiwi_merchant_prepare_products_import",
+                // 幂等由 operation store 承载（同幂等键返回同一 operation），前置版本
+                // 用静态摘要（导入是批量意图，不因目录其他变化失效）。
+                readPreconditions: async (args) => ({
+                    idempotency_key: String(args.idempotency_key ?? ""),
+                    lines: String(args.csv ?? "")
+                        .split(/\r?\n/)
+                        .filter((l) => l.trim() !== "").length,
+                }),
+                execute: async (args, c) => {
+                    if (c.operations === undefined) {
+                        throw new Error("operation store 未配置（不可得）");
+                    }
+                    return executeProductsImport({
+                        csv: String(args.csv ?? ""),
+                        idempotencyKey: String(args.idempotency_key ?? ""),
+                        merchantId: c.ownerId,
+                        merchantClient: c.merchantClient,
+                        operations: c.operations,
+                    });
+                },
+            },
+            {
+                // F04 撤回（listing 销售状态语义；上游无端点 → 逐项回执失败，不库存写零）。
+                tool: "kiwi_merchant_prepare_products_withdraw",
+                readPreconditions: async (args) => ({
+                    skus: Array.isArray(args.skus) ? args.skus.length : 0,
+                }),
+                execute: async (args, c) => {
+                    if (c.operations === undefined) {
+                        throw new Error("operation store 未配置（不可得）");
+                    }
+                    const skus = Array.isArray(args.skus) ? args.skus.map(String) : [];
+                    const op = c.operations.createOrGet({
+                        kind: "products_withdraw",
+                        idempotencyKey: String(args.idempotency_key ?? ""),
+                    });
+                    if (!op.created)
+                        return op.operation; // 幂等：不重复撤回
+                    c.operations.markRunning(op.operation.operation_id);
+                    const receipts = [];
+                    for (const sku of skus) {
+                        try {
+                            await c.merchantClient.pauseListing(sku, true);
+                            receipts.push({ item: sku, ok: true });
+                        }
+                        catch (err) {
+                            receipts.push({
+                                item: sku,
+                                ok: false,
+                                detail: err instanceof Error ? err.message : String(err),
+                            });
+                        }
+                    }
+                    const finished = c.operations.finish(op.operation.operation_id, receipts);
+                    // 全部项失败 → ok:false（审查 P1：否则候选仍被标 executed，审计谎报成功）
+                    return finished.status === "failed" ? { ok: false, operation: finished } : finished;
+                },
+            },
+        ]);
+    }
+    get(tool) {
+        return this.registry.get(tool);
+    }
+    has(tool) {
+        return this.registry.has(tool);
+    }
+    tools() {
+        return [...this.registry.keys()];
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/merchant-core/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/merchant-core/executor.ts"],"names":[],"mappings":"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"}

package/dist/merchant-core/negotiation-adapters.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 两轨磋商适配器（V2 §5.2；阶段二）。
+ *
+ * Kiwi Merchant 同时存在两条磋商轨：
+ *   - a2a：A2A/KNP 轨（Ledger 权威，相位机状态名 OPEN/OFFER_OPEN/…）；
+ *   - shopping：shopping-cli 会话轨（conversation 状态名 waiting_merchant/…）。
+ *
+ * 统一列表：每条携带 source_protocol 与 source_id；详情保留各自协议的
+ * 状态名（不抹平）。人工处理入口按来源路由——A2A 人审走 A2A 侧机制，
+ * 绝不调 shopping-cli resolve-review；shopping 轨才走上游接口。
+ */
+import type { IncomingConsultation } from "../agent/merchant/types.js";
+import type { A2aNegotiationRow } from "../merchant/workbench-service.js";
+/** 磋商来源协议（两轨）。 */
+export type NegotiationSourceProtocol = "a2a" | "shopping";
+/** 统一磋商列表行（状态名保留各自协议口径，不抹平）。 */
+export interface UnifiedNegotiationRow {
+    source_protocol: NegotiationSourceProtocol;
+    /** 轨道内 id：a2a = negotiation_id；shopping = conversation_id。 */
+    source_id: string;
+    /** 协议原生状态名（a2a 相位 / shopping 会话 status）。 */
+    status: string;
+    sku?: string;
+    buyer?: string;
+    updated_at: string;
+    needs_human_review: boolean;
+}
+/** A2A 轨行 → 统一行。needsHumanReview 由调用方按轨道语义计算传入
+ *  （A2A 侧权威口径在 intelligence 的 extractNegotiation：AWAITING_CLARIFICATION
+ *  或「非终态且最后一条为买家入站等待商家回应」）。 */
+export declare function fromA2aRow(row: A2aNegotiationRow, needsHumanReview: boolean): UnifiedNegotiationRow;
+/** shopping 会话轨行 → 统一行。 */
+export declare function fromShoppingConsultation(c: IncomingConsultation): UnifiedNegotiationRow;
+/** 人工处理路由（V2 §5.2）：按来源返回处理通道，跨轨调用直接拒绝。 */
+export declare function routeHumanReview(row: UnifiedNegotiationRow): "a2a" | "shopping";
+/**
+ * 路由守卫：对 A2A 来源的磋商调用 shopping 轨处理接口（resolve-review）是
+ * 协议错误——fail-closed 抛错，绝不跨轨执行。
+ */
+export declare function assertReviewRoute(sourceProtocol: NegotiationSourceProtocol, channel: "a2a" | "shopping"): void;

package/dist/merchant-core/negotiation-adapters.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** A2A 轨行 → 统一行。needsHumanReview 由调用方按轨道语义计算传入
+ *  （A2A 侧权威口径在 intelligence 的 extractNegotiation：AWAITING_CLARIFICATION
+ *  或「非终态且最后一条为买家入站等待商家回应」）。 */
+export function fromA2aRow(row, needsHumanReview) {
+    return {
+        source_protocol: "a2a",
+        source_id: row.negotiation_id,
+        status: row.phase,
+        ...(row.sku !== "" ? { sku: row.sku } : {}),
+        updated_at: row.recorded_at,
+        needs_human_review: needsHumanReview,
+    };
+}
+/** shopping 会话轨行 → 统一行。 */
+export function fromShoppingConsultation(c) {
+    return {
+        source_protocol: "shopping",
+        source_id: c.conversation_id,
+        status: c.status,
+        ...(c.sku !== undefined ? { sku: c.sku } : {}),
+        ...(c.buyer_id !== undefined ? { buyer: c.buyer_id } : {}),
+        updated_at: c.last_message_at,
+        needs_human_review: c.status === "human_required",
+    };
+}
+/** 人工处理路由（V2 §5.2）：按来源返回处理通道，跨轨调用直接拒绝。 */
+export function routeHumanReview(row) {
+    return row.source_protocol;
+}
+/**
+ * 路由守卫：对 A2A 来源的磋商调用 shopping 轨处理接口（resolve-review）是
+ * 协议错误——fail-closed 抛错，绝不跨轨执行。
+ */
+export function assertReviewRoute(sourceProtocol, channel) {
+    if (sourceProtocol !== channel) {
+        throw new Error(`人工处理路由错误：${sourceProtocol} 轨磋商不能走 ${channel} 通道` +
+            "（A2A 人审走 A2A 侧机制，shopping 轨才走 shopping-cli resolve-review）");
+    }
+}
+//# sourceMappingURL=negotiation-adapters.js.map

package/dist/merchant-core/negotiation-adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"negotiation-adapters.js","sourceRoot":"","sources":["../../src/merchant-core/negotiation-adapters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiCH;;+BAE+B;AAC/B,MAAM,UAAU,UAAU,CACxB,GAAsB,EACtB,gBAAyB;IAEzB,OAAO;QACL,eAAe,EAAE,KAAK;QACtB,SAAS,EAAE,GAAG,CAAC,cAAc;QAC7B,MAAM,EAAE,GAAG,CAAC,KAAK;QACjB,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,UAAU,EAAE,GAAG,CAAC,WAAW;QAC3B,kBAAkB,EAAE,gBAAgB;KACrC,CAAC;AACJ,CAAC;AAED,2BAA2B;AAC3B,MAAM,UAAU,wBAAwB,CAAC,CAAuB;IAC9D,OAAO;QACL,eAAe,EAAE,UAAU;QAC3B,SAAS,EAAE,CAAC,CAAC,eAAe;QAC5B,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,UAAU,EAAE,CAAC,CAAC,eAAe;QAC7B,kBAAkB,EAAE,CAAC,CAAC,MAAM,KAAK,gBAAgB;KAClD,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB,CAAC,GAA0B;IACzD,OAAO,GAAG,CAAC,eAAe,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,cAAyC,EACzC,OAA2B;IAE3B,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,YAAY,cAAc,WAAW,OAAO,KAAK;YAC/C,4DAA4D,CAC/D,CAAC;IACJ,CAAC;AACH,CAAC"}