@harrylabsj/kiwi 0.6.0

package/dist/agent/merchant/action-candidate.js

@@ -0,0 +1,241 @@
+/**
+ * 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.
+ */
+/**
+ * Approval WriteApprovalCandidates (design §16).
+ *
+ * The operator approves a specific argument set against a specific
+ * precondition state — never a free-form "agree". A candidate carries:
+ *   candidate_id, tool, arguments_hash, preconditions_hash, risk, expires_at.
+ *
+ * Execution re-reads the preconditions (product / inventory / conversation /
+ * task state) and re-hashes them. If the state changed since the candidate
+ * was created, the old approval is invalid: the candidate is superseded and
+ * must be regenerated. The store is a plain SQLite-backed persistence layer;
+ * the lifecycle routing (mode -> pending_approval / auto-execute) lives in
+ * the tool layer.
+ *
+ * Privacy invariant: arguments_json / preconditions_json hold only public
+ * catalog/inventory/task facts. Restricted values (private floors, costs)
+ * never enter this table, the event log or model-visible output.
+ */
+import { createHash } from "node:crypto";
+import { uuidv7 } from "@earendil-works/pi-ai";
+export const WRITE_APPROVAL_CANDIDATE_STATUSES = [
+    "pending_approval",
+    "approved",
+    "executed",
+    "rejected",
+    "superseded",
+    "expired",
+];
+export class WriteApprovalCandidateError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "WriteApprovalCandidateError";
+        this.code = code;
+    }
+}
+/**
+ * Deterministic canonical serialization (sorted keys, no undefined) so equal
+ * argument sets always hash identically — content addressing across retries
+ * and restarts.
+ */
+export function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "null";
+}
+/** sha256 content hash of a structured value, prefixed for audit clarity. */
+export function contentHash(value) {
+    return `sha256:${createHash("sha256").update(stableStringify(value)).digest("hex")}`;
+}
+export class WriteApprovalCandidateStore {
+    db;
+    principalId;
+    now;
+    constructor(options) {
+        this.db = options.db;
+        this.principalId = options.principalId;
+        const clock = options.now ?? (() => new Date().toISOString());
+        this.now = () => new Date(Date.parse(clock())).toISOString();
+    }
+    create(input) {
+        const candidateId = `act_${uuidv7()}`;
+        const now = this.now();
+        this.db
+            .prepare(`INSERT INTO action_candidates
+           (candidate_id, principal_id, task_id, tool, arguments_json, arguments_hash,
+            preconditions_json, preconditions_hash, risk, status, expires_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending_approval', ?, ?, ?)`)
+            .run(candidateId, this.principalId, input.task_id ?? null, input.tool, JSON.stringify(input.arguments), contentHash(input.arguments), JSON.stringify(input.preconditions), contentHash(input.preconditions), input.risk, input.expires_at, now, now);
+        return this.get(candidateId);
+    }
+    get(candidateId) {
+        const row = this.db
+            .prepare("SELECT * FROM action_candidates WHERE candidate_id = ? AND principal_id = ?")
+            .get(candidateId, this.principalId);
+        return row === undefined ? undefined : this.rowToCandidate(row);
+    }
+    listPending() {
+        this.expireDue();
+        const rows = this.db
+            .prepare("SELECT * FROM action_candidates WHERE principal_id = ? AND status = 'pending_approval' ORDER BY created_at, candidate_id")
+            .all(this.principalId);
+        return rows.map((r) => this.rowToCandidate(r));
+    }
+    /** Expire pending/approved candidates past their deadline. Returns count. */
+    expireDue() {
+        const now = this.now();
+        const due = this.db
+            .prepare(`SELECT candidate_id FROM action_candidates
+         WHERE principal_id = ? AND status IN ('pending_approval','approved') AND expires_at < ?`)
+            .all(this.principalId, now);
+        for (const { candidate_id } of due) {
+            this.db
+                .prepare("UPDATE action_candidates SET status = 'expired', updated_at = ? WHERE candidate_id = ?")
+                .run(now, candidate_id);
+        }
+        return due.length;
+    }
+    setStatus(candidateId, status) {
+        const existing = this.get(candidateId);
+        if (existing === undefined)
+            throw new WriteApprovalCandidateError("not_found", `no candidate ${candidateId}`);
+        this.db
+            .prepare("UPDATE action_candidates SET status = ?, updated_at = ? WHERE candidate_id = ?")
+            .run(status, this.now(), candidateId);
+        return this.get(candidateId);
+    }
+    /** Record operator approval (idempotent on already-approved/executed). */
+    markApproved(candidateId) {
+        this.expireDue();
+        const existing = this.get(candidateId);
+        if (existing === undefined)
+            throw new WriteApprovalCandidateError("not_found", `no candidate ${candidateId}`);
+        if (existing.status === "executed" || existing.status === "approved")
+            return existing;
+        if (existing.status === "expired")
+            throw new WriteApprovalCandidateError("expired", `candidate ${candidateId} expired`);
+        if (existing.status !== "pending_approval") {
+            throw new WriteApprovalCandidateError("conflict", `candidate ${candidateId} is ${existing.status}, not approvable`);
+        }
+        return this.setStatus(candidateId, "approved");
+    }
+    markExecuted(candidateId) {
+        return this.setStatus(candidateId, "executed");
+    }
+    reject(candidateId) {
+        return this.setStatus(candidateId, "rejected");
+    }
+    supersede(candidateId) {
+        return this.setStatus(candidateId, "superseded");
+    }
+    rowToCandidate(row) {
+        const candidate = {
+            candidate_id: row.candidate_id,
+            principal_id: row.principal_id,
+            tool: row.tool,
+            arguments: JSON.parse(row.arguments_json),
+            arguments_hash: row.arguments_hash,
+            preconditions: JSON.parse(row.preconditions_json),
+            preconditions_hash: row.preconditions_hash,
+            risk: row.risk,
+            status: row.status,
+            expires_at: row.expires_at,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        };
+        if (row.task_id !== null)
+            candidate.task_id = row.task_id;
+        return candidate;
+    }
+}
+/**
+ * Execute an approved candidate after re-validating its preconditions (§16):
+ *  1. The candidate must be `approved` and not past its deadline.
+ *  2. Preconditions are re-read from the current marketplace/task state and
+ *     re-hashed. A different hash means the old approval no longer applies —
+ *     the candidate is superseded and nothing is executed.
+ *  3. Only the STORED arguments (what the operator approved) are executed,
+ *     never anything re-read from the model.
+ */
+export async function executeApprovedCandidate(store, candidateId, hooks) {
+    const candidate = store.get(candidateId);
+    if (candidate === undefined) {
+        throw new WriteApprovalCandidateError("not_found", `no candidate ${candidateId}`);
+    }
+    if (candidate.status === "expired")
+        return { kind: "expired", candidate };
+    if (candidate.status !== "approved") {
+        return {
+            kind: "not_approvable",
+            candidate,
+            reason: `候选 ${candidateId} 状态为 ${candidate.status}，不是 approved；不会执行。`,
+        };
+    }
+    const freshPreconditions = await hooks.readPreconditions();
+    const freshHash = contentHash(freshPreconditions);
+    if (freshHash !== candidate.preconditions_hash) {
+        store.supersede(candidateId);
+        return {
+            kind: "stale",
+            candidate: store.get(candidateId),
+            reason: "前置状态已变化（preconditions_hash 不匹配），旧批准失效；已标记 superseded，请重新生成候选。",
+        };
+    }
+    let output;
+    try {
+        output = await hooks.execute(candidate.arguments);
+    }
+    catch (err) {
+        // 执行体抛错（评审项 P3-4）：网络中断等异常会让候选停留在 approved——
+        // 操作者可再次 /approve，而执行体（如 start_consultation：先在外网创建
+        // 会话、再本地落账）可能在首次执行已完成外部副作用后抛错——重试会重复
+        // 创建外部会话（幂等键依赖新的 conversation_id，不构成防护）。标
+        // superseded 防重复批准，返回 stale 让调用方提示重新生成候选。
+        store.supersede(candidateId);
+        return {
+            kind: "stale",
+            candidate: store.get(candidateId),
+            reason: `执行抛错（${err instanceof Error ? err.message : String(err)}），候选已失效，请重新生成候选。`,
+        };
+    }
+    // 执行失败（如 handoff 候选已 stale/expired，execute 返回 {ok:false} 而非
+    // 抛错）→ 审批候选不标 executed：审计状态不得与 Ledger 矛盾（此前无条件
+    // markExecuted，/approve 显示"已执行"但链上实际无交付）。标 superseded
+    // 防重复批准，返回 stale 让调用方提示重新生成候选。
+    if (output !== null &&
+        typeof output === "object" &&
+        output.ok === false) {
+        store.supersede(candidateId);
+        return {
+            kind: "stale",
+            candidate: store.get(candidateId),
+            reason: "执行失败（execute 返回非成功结果），候选已失效，请重新生成候选。",
+        };
+    }
+    const executed = store.markExecuted(candidateId);
+    return { kind: "executed", candidate: executed, output };
+}
+//# sourceMappingURL=action-candidate.js.map

package/dist/agent/merchant/action-candidate.js.map

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

package/dist/agent/merchant/credential-broker.d.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+/**
+ * Credential Broker (design §15.4).
+ *
+ * Negotiation / catalog / inventory credentials are held separately by scope.
+ * The model only ever sees tools — never tokens. A write tool whose scope has
+ * no credential configured fails closed: it refuses to touch the marketplace
+ * rather than degrading to an unauthenticated or mis-scoped call.
+ *
+ * The negotiation scope is the profile's primary `commerce.token_env`;
+ * catalog and inventory scopes come from the optional
+ * `commerce.credentials.<scope>.token_env` refs. Tokens are resolved lazily at
+ * call time via process.env, exactly like the negotiation token — nothing is
+ * ever stored in the profile or in logs.
+ */
+import type { CommerceCredentialScope } from "../../config/profile.js";
+import type { AgentProfile } from "../../config/profile.js";
+/** The broker never logs or exposes token values; only scopes are queryable. */
+export interface CredentialBroker {
+    /** Token for a scope, or undefined when that scope is not configured. */
+    resolve(scope: CommerceCredentialScope): string | undefined;
+    /** Whether a token is configured for the scope (not whether it is valid). */
+    has(scope: CommerceCredentialScope): boolean;
+}
+/** Fail-closed helper shared by write tools: no credential -> refuse. */
+export declare function requireScopeCredential(broker: CredentialBroker, scope: CommerceCredentialScope): {
+    ok: true;
+    token: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Env-backed broker derived from a profile's commerce credential refs. */
+export declare class ProfileCredentialBroker implements CredentialBroker {
+    private readonly profile;
+    constructor(profile: AgentProfile);
+    resolve(scope: CommerceCredentialScope): string | undefined;
+    has(scope: CommerceCredentialScope): boolean;
+}
+/** Explicit-map broker for tests and embedded use (keys are env-var names). */
+export declare class EnvRefCredentialBroker implements CredentialBroker {
+    private readonly refs;
+    constructor(refs: Partial<Record<CommerceCredentialScope, string>>);
+    resolve(scope: CommerceCredentialScope): string | undefined;
+    has(scope: CommerceCredentialScope): boolean;
+}
+/** Literal-value broker for deterministic tests (values never logged). */
+export declare class StaticCredentialBroker implements CredentialBroker {
+    private readonly tokens;
+    constructor(tokens: Partial<Record<CommerceCredentialScope, string>>);
+    resolve(scope: CommerceCredentialScope): string | undefined;
+    has(scope: CommerceCredentialScope): boolean;
+}

package/dist/agent/merchant/credential-broker.js

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+/** Fail-closed helper shared by write tools: no credential -> refuse. */
+export function requireScopeCredential(broker, scope) {
+    const token = broker.resolve(scope);
+    if (token === undefined || token === "") {
+        return {
+            ok: false,
+            reason: `没有 ${scope} 作用域的凭据（commerce.credentials.${scope}.token_env 未配置），` +
+                `该写操作已安全拒绝（fail closed）。`,
+        };
+    }
+    return { ok: true, token };
+}
+/** Resolve a token from an env-var reference, never logging the value. */
+function resolveEnv(envName) {
+    if (envName === undefined)
+        return undefined;
+    const value = process.env[envName];
+    return value === undefined || value === "" ? undefined : value;
+}
+/** Env-backed broker derived from a profile's commerce credential refs. */
+export class ProfileCredentialBroker {
+    profile;
+    constructor(profile) {
+        this.profile = profile;
+    }
+    resolve(scope) {
+        if (scope === "negotiation")
+            return resolveEnv(this.profile.commerce.token_env);
+        return resolveEnv(this.profile.commerce.credentials?.[scope]?.token_env);
+    }
+    has(scope) {
+        return this.resolve(scope) !== undefined;
+    }
+}
+/** Explicit-map broker for tests and embedded use (keys are env-var names). */
+export class EnvRefCredentialBroker {
+    refs;
+    constructor(refs) {
+        this.refs = refs;
+    }
+    resolve(scope) {
+        return resolveEnv(this.refs[scope]);
+    }
+    has(scope) {
+        return this.resolve(scope) !== undefined;
+    }
+}
+/** Literal-value broker for deterministic tests (values never logged). */
+export class StaticCredentialBroker {
+    tokens;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    resolve(scope) {
+        return this.tokens[scope];
+    }
+    has(scope) {
+        return this.tokens[scope] !== undefined && this.tokens[scope] !== "";
+    }
+}
+//# sourceMappingURL=credential-broker.js.map

package/dist/agent/merchant/credential-broker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-broker.js","sourceRoot":"","sources":["../../../src/agent/merchant/credential-broker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA4BH,yEAAyE;AACzE,MAAM,UAAU,sBAAsB,CACpC,MAAwB,EACxB,KAA8B;IAE9B,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,MAAM,KAAK,gCAAgC,KAAK,kBAAkB;gBAClE,yBAAyB;SAC5B,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,0EAA0E;AAC1E,SAAS,UAAU,CAAC,OAA2B;IAC7C,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AACjE,CAAC;AAED,2EAA2E;AAC3E,MAAM,OAAO,uBAAuB;IACjB,OAAO,CAAe;IAEvC,YAAY,OAAqB;QAC/B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,OAAO,CAAC,KAA8B;QACpC,IAAI,KAAK,KAAK,aAAa;YAAE,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAChF,OAAO,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;IAC3E,CAAC;IAED,GAAG,CAAC,KAA8B;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;IAC3C,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,OAAO,sBAAsB;IAChB,IAAI,CAAmD;IAExE,YAAY,IAAsD;QAChE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;IAED,OAAO,CAAC,KAA8B;QACpC,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,KAA8B;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;IAC3C,CAAC;CACF;AAED,0EAA0E;AAC1E,MAAM,OAAO,sBAAsB;IAChB,MAAM,CAAmD;IAE1E,YAAY,MAAwD;QAClE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,OAAO,CAAC,KAA8B;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC5B,CAAC;IAED,GAAG,CAAC,KAA8B;QAChC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACvE,CAAC;CACF"}

package/dist/agent/merchant/fake-merchant-client.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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 type { HumanReviewItem, IncomingConsultation, InventorySnapshot, MerchantCatalogProduct, MerchantClient, MerchantProductInput, MerchantProductPatch } from "./types.js";
+export declare class FakeMerchantClient implements MerchantClient {
+    private readonly products;
+    private readonly consultations;
+    private readonly reviews;
+    private now;
+    constructor(options?: {
+        products?: MerchantCatalogProduct[];
+        consultations?: IncomingConsultation[];
+        reviews?: HumanReviewItem[];
+        now?: string;
+    });
+    /** Test helper: advance the fake clock. */
+    advanceTime(ms: number): void;
+    /** Test helper: add or replace a catalog product. */
+    put(product: MerchantCatalogProduct): void;
+    /** Test helper: push an incoming consultation. */
+    addConsultation(c: IncomingConsultation): void;
+    listProducts(merchantId: string): Promise<MerchantCatalogProduct[]>;
+    getProduct(sku: string): Promise<MerchantCatalogProduct>;
+    createProduct(input: MerchantProductInput): Promise<MerchantCatalogProduct>;
+    updateProduct(sku: string, patch: MerchantProductPatch): Promise<MerchantCatalogProduct>;
+    getInventorySnapshot(sku: string): Promise<InventorySnapshot>;
+    /** Inventory-scope write, always against a fresh read of the product. */
+    updateInventory(sku: string, stock: number): Promise<MerchantCatalogProduct>;
+    listIncomingConsultations(merchantId: string): Promise<IncomingConsultation[]>;
+    getHumanReviewQueue(merchantId: string): Promise<HumanReviewItem[]>;
+    pauseListing(sku: string, paused: boolean): Promise<MerchantCatalogProduct>;
+    private requireProduct;
+}
+/** A merchant catalog fixture with shopping-cli field shapes. */
+export declare function fakeMerchantProduct(overrides?: Partial<MerchantCatalogProduct>): MerchantCatalogProduct;

package/dist/agent/merchant/fake-merchant-client.js

@@ -0,0 +1,143 @@
+/**
+ * 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.
+ */
+/**
+ * Deterministic in-memory MerchantClient for tests and offline smoke runs.
+ * Mirrors the shopping-cli catalog/consultation semantics closely enough that
+ * merchant capability tools can be exercised end-to-end without a gateway:
+ * catalog CRUD, inventory snapshot, incoming consultations, human-review queue
+ * and the paused listing flag. Private merchant values (floor/cost) are NOT
+ * here — they live in the Vault / profile and never enter this client.
+ */
+import { MerchantClientError } from "./types.js";
+export class FakeMerchantClient {
+    products = new Map();
+    consultations = [];
+    reviews = [];
+    now;
+    constructor(options = {}) {
+        for (const p of options.products ?? [])
+            this.products.set(p.sku, p);
+        this.consultations.push(...(options.consultations ?? []));
+        this.reviews.push(...(options.reviews ?? []));
+        this.now = options.now ?? "2026-08-03T15:00:00+08:00";
+    }
+    /** Test helper: advance the fake clock. */
+    advanceTime(ms) {
+        this.now = new Date(Date.parse(this.now) + ms).toISOString();
+    }
+    /** Test helper: add or replace a catalog product. */
+    put(product) {
+        this.products.set(product.sku, product);
+    }
+    /** Test helper: push an incoming consultation. */
+    addConsultation(c) {
+        this.consultations.push(c);
+    }
+    async listProducts(merchantId) {
+        return [...this.products.values()].filter((p) => p.merchant_id === merchantId);
+    }
+    async getProduct(sku) {
+        const product = this.products.get(sku);
+        if (product === undefined) {
+            throw new MerchantClientError("not_found", `no product ${sku}`);
+        }
+        return product;
+    }
+    async createProduct(input) {
+        if (this.products.has(input.sku)) {
+            throw new MerchantClientError("validation", `product ${input.sku} already exists`);
+        }
+        const product = {
+            sku: input.sku,
+            merchant_id: input.merchant_id,
+            title: input.title,
+            description: input.description ?? "",
+            category: input.category ?? "",
+            tags: input.tags ?? [],
+            price: input.price,
+            currency: input.currency ?? "CNY",
+            stock: input.stock,
+            delivery_attributes: input.delivery_attributes ?? [],
+            paused: false,
+        };
+        this.products.set(product.sku, product);
+        return product;
+    }
+    async updateProduct(sku, patch) {
+        const product = this.requireProduct(sku);
+        const updated = {
+            ...product,
+            ...(patch.title !== undefined ? { title: patch.title } : {}),
+            ...(patch.price !== undefined ? { price: patch.price } : {}),
+            ...(patch.stock !== undefined ? { stock: patch.stock } : {}),
+            ...(patch.currency !== undefined ? { currency: patch.currency } : {}),
+            ...(patch.category !== undefined ? { category: patch.category } : {}),
+            ...(patch.tags !== undefined ? { tags: patch.tags } : {}),
+            ...(patch.description !== undefined ? { description: patch.description } : {}),
+            ...(patch.delivery_attributes !== undefined
+                ? { delivery_attributes: patch.delivery_attributes }
+                : {}),
+        };
+        this.products.set(sku, updated);
+        return updated;
+    }
+    async getInventorySnapshot(sku) {
+        const product = await this.getProduct(sku);
+        return { sku: product.sku, stock: product.stock, observed_at: this.now };
+    }
+    /** Inventory-scope write, always against a fresh read of the product. */
+    async updateInventory(sku, stock) {
+        return this.updateProduct(sku, { stock });
+    }
+    async listIncomingConsultations(merchantId) {
+        return this.consultations.filter((c) => {
+            const product = this.products.get(c.sku ?? "");
+            return product === undefined || product.merchant_id === merchantId;
+        });
+    }
+    async getHumanReviewQueue(merchantId) {
+        const owned = new Set([...this.products.values()].filter((p) => p.merchant_id === merchantId).map((p) => p.sku));
+        return this.reviews.filter((r) => owned.has(r.sku));
+    }
+    async pauseListing(sku, paused) {
+        return this.updateProduct(sku, { paused });
+    }
+    requireProduct(sku) {
+        const product = this.products.get(sku);
+        if (product === undefined) {
+            throw new MerchantClientError("not_found", `no product ${sku}`);
+        }
+        return product;
+    }
+}
+/** A merchant catalog fixture with shopping-cli field shapes. */
+export function fakeMerchantProduct(overrides = {}) {
+    return {
+        sku: "sku-001",
+        merchant_id: "merchant-001",
+        title: "手写陶瓷杯",
+        description: "手工拉坯，350ml",
+        category: "kitchenware",
+        tags: ["手工", "陶瓷"],
+        price: 99,
+        currency: "CNY",
+        stock: 12,
+        delivery_attributes: [],
+        paused: false,
+        ...overrides,
+    };
+}
+//# sourceMappingURL=fake-merchant-client.js.map

package/dist/agent/merchant/fake-merchant-client.js.map

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

package/dist/agent/merchant/merchant-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/**
+ * shopping-cli HTTP Merchant client (design §15.3/§15.4).
+ *
+ * Catalog/inventory/conversation reads and writes against the real gateway.
+ * Tokens come from the CredentialBroker per scope: catalog writes and
+ * merchant-scoped reads use the catalog credential, inventory writes use the
+ * inventory credential. Tokens are attached per-request and never stored.
+ *
+ * Trade-off (fail-closed): shopping-cli 2.x has no listing pause/resume
+ * endpoint (`active` is internal to the catalog), so pauseListing refuses
+ * here with a clear message — the approval machinery still runs, only the
+ * final write is refused.
+ */
+import type { CredentialBroker } from "./credential-broker.js";
+import type { HumanReviewItem, IncomingConsultation, InventorySnapshot, MerchantCatalogProduct, MerchantClient, MerchantProductInput, MerchantProductPatch } from "./types.js";
+export declare class HttpMerchantClient implements MerchantClient {
+    private readonly baseUrl;
+    private readonly broker;
+    constructor(baseUrl: string, broker: CredentialBroker);
+    private request;
+    /** Catalog credential token; missing scope -> fail closed. */
+    private catalogToken;
+    listProducts(merchantId: string): Promise<MerchantCatalogProduct[]>;
+    getProduct(sku: string): Promise<MerchantCatalogProduct>;
+    createProduct(input: MerchantProductInput): Promise<MerchantCatalogProduct>;
+    updateProduct(sku: string, patch: MerchantProductPatch): Promise<MerchantCatalogProduct>;
+    getInventorySnapshot(sku: string): Promise<InventorySnapshot>;
+    /** Inventory-scope write: PATCH only the stock field with the inventory token. */
+    updateInventory(sku: string, stock: number): Promise<MerchantCatalogProduct>;
+    listIncomingConsultations(merchantId: string): Promise<IncomingConsultation[]>;
+    getHumanReviewQueue(merchantId: string): Promise<HumanReviewItem[]>;
+    /** shopping-cli 2.x has no listing pause endpoint — fail closed. */
+    pauseListing(_sku: string, _paused: boolean): Promise<MerchantCatalogProduct>;
+}