@harrylabsj/kiwi 0.6.0

package/dist/commerce/shopping-cli-source.js

@@ -0,0 +1,206 @@
+/**
+ * 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.
+ */
+/**
+ * ShoppingCliCommerceDataSource —— shopping-cli 商品开放层 adapter
+ * （shopping-cli data hub v0.2.1 §3/#5：shopping-cli 可作为 Merchant
+ * CommerceDataSource，完成定义 #5）。
+ *
+ * 端点契约（shopping-cli 仓 route_registry）：
+ *   GET {baseUrl}/products/{sku}        → {product: {...}}
+ *   GET {baseUrl}/search/products?limit= → {results: [...]}
+ *
+ * 字段语义：
+ *   - shopping-cli 的 `price` 以「元」为单位（float）→ 转换为
+ *     `price_minor`（minor units，KNP Money 约定；两位小数假设，文档注明）；
+ *   - 权威语义 UPSTREAM_PROXY（数据权威在 shopping-cli 侧，Kiwi 只读）。
+ */
+import { CommerceError } from "./data-source.js";
+import { isRedirectResponse, readJsonBody, SafeHttpError } from "../net/safe-http.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+function validateBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new CommerceError("invalid_input", `shopping-cli baseUrl is not a valid URL: "${value}"`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new CommerceError("invalid_input", `shopping-cli baseUrl must use http or https (got ${url.protocol})`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new CommerceError("invalid_input", "shopping-cli baseUrl must not embed credentials (userinfo)");
+    }
+    if (url.search !== "" || url.hash !== "") {
+        throw new CommerceError("invalid_input", "shopping-cli baseUrl must not contain query or fragment (paths are appended to it)");
+    }
+    return value.replace(/\/+$/, "");
+}
+/** shopping-cli price（元）→ price_minor（minor units，两位小数假设）。 */
+function toMinorUnits(price) {
+    if (typeof price !== "number" || !Number.isFinite(price) || price < 0)
+        return undefined;
+    return Math.round(price * 100);
+}
+function parseProduct(raw, path) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new CommerceError("request_failed", `shopping-cli product at ${path} is not an object`);
+    }
+    const obj = raw;
+    const sku = obj.sku;
+    if (typeof sku !== "string" || sku.length === 0) {
+        throw new CommerceError("request_failed", `shopping-cli product at ${path} is missing sku`);
+    }
+    const priceMinor = toMinorUnits(obj.price);
+    return {
+        sku,
+        ...(typeof obj.title === "string" && obj.title !== "" ? { title: obj.title } : {}),
+        ...(priceMinor !== undefined ? { price_minor: priceMinor } : {}),
+        ...(typeof obj.currency === "string" && obj.currency !== "" ? { currency: obj.currency } : {}),
+        ...(typeof obj.stock === "number" && Number.isInteger(obj.stock) ? { stock: obj.stock } : {}),
+    };
+}
+/** shopping-cli 商品开放层数据源（UPSTREAM_PROXY，source="shopping-cli"）。 */
+export class ShoppingCliCommerceDataSource {
+    baseUrl;
+    deps;
+    constructor(deps) {
+        this.baseUrl = validateBaseUrl(deps.baseUrl);
+        this.deps = deps;
+    }
+    async getJson(requestPath) {
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${requestPath}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                // 出站加固：绝不跟随重定向（3xx 目标不经过校验，且可能转发 Bearer 头）。
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    accept: "application/json",
+                    ...(this.deps.authToken !== undefined
+                        ? { authorization: `Bearer ${this.deps.authToken}` }
+                        : {}),
+                },
+            });
+        }
+        catch (err) {
+            const name = err?.name;
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new CommerceError("request_failed", name === "AbortError"
+                ? `shopping-cli request timed out after ${timeoutMs}ms: ${url}`
+                : `shopping-cli request failed: ${url} (${detail})`);
+        }
+        if (isRedirectResponse(response)) {
+            throw new CommerceError("request_failed", `shopping-cli request must not follow redirects (HTTP ${response.status} from ${url})`);
+        }
+        if (response.status === 404) {
+            // 404 = 资源不存在：getProduct 的"未知 SKU → undefined"接口承诺
+            //（composite 次要源靠它跳过自身不收录的 SKU，而不是整体抛错）。
+            return null;
+        }
+        if (!response.ok) {
+            throw new CommerceError("request_failed", `shopping-cli request returned HTTP ${response.status} from ${url}`);
+        }
+        let raw;
+        try {
+            // 响应体读取在超时覆盖内 + 大小上限（出站加固）。
+            raw = await readJsonBody(response, { signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new CommerceError("request_failed", `shopping-cli request timed out after ${timeoutMs}ms while reading response: ${url}`);
+            }
+            throw new CommerceError("request_failed", err instanceof SafeHttpError && err.code === "response_too_large"
+                ? `shopping-cli response from ${url}: ${err.message}`
+                : `shopping-cli response from ${url} is not valid JSON`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return raw;
+    }
+    async getProduct(sku) {
+        if (typeof sku !== "string" || sku.length === 0) {
+            throw new CommerceError("invalid_input", "sku must be a non-empty string");
+        }
+        const raw = await this.getJson(`/products/${encodeURIComponent(sku)}`);
+        if (raw === null)
+            return undefined; // 404 → 未知 SKU（接口承诺）
+        if (typeof raw !== "object" || Array.isArray(raw)) {
+            throw new CommerceError("request_failed", "shopping-cli get product response must be an object");
+        }
+        const body = raw;
+        if (body.product === undefined) {
+            throw new CommerceError("request_failed", 'shopping-cli get product response is missing field "product"');
+        }
+        return parseProduct(body.product, `/products/${sku}`);
+    }
+    async getProducts(query = {}) {
+        const limit = Math.max(1, Math.min(Number(query.limit ?? 20) || 20, 100));
+        const params = new URLSearchParams();
+        params.set("limit", String(limit));
+        if (query.q !== undefined && query.q !== "")
+            params.set("q", query.q);
+        const raw = await this.getJson(`/search/products?${params.toString()}`);
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new CommerceError("request_failed", "shopping-cli search products response must be an object");
+        }
+        const body = raw;
+        if (!Array.isArray(body.results)) {
+            throw new CommerceError("request_failed", 'shopping-cli search products response is missing array field "results"');
+        }
+        return body.results.map((element, i) => parseProduct(element, `/search/products/${i}`));
+    }
+    async getInventory(sku) {
+        const product = await this.getProduct(sku);
+        if (product?.stock === undefined)
+            return undefined;
+        return { value: product.stock, authority: "UPSTREAM_PROXY", source: "shopping-cli" };
+    }
+    async getPrice(sku) {
+        const product = await this.getProduct(sku);
+        if (product?.price_minor === undefined || product.currency === undefined)
+            return undefined;
+        return {
+            value: { currency: product.currency, amount_minor: product.price_minor },
+            authority: "UPSTREAM_PROXY",
+            source: "shopping-cli",
+        };
+    }
+    async getPublicListing() {
+        const products = await this.getProducts({ limit: 100 });
+        return { source: "shopping-cli", count: products.length, products };
+    }
+    async health() {
+        try {
+            await this.getJson("/health");
+            return { ok: true, service: "shopping-cli-commerce-data-source", version: "1" };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                service: "shopping-cli-commerce-data-source",
+                details: { error: err instanceof Error ? err.message : String(err) },
+            };
+        }
+    }
+}
+//# sourceMappingURL=shopping-cli-source.js.map

package/dist/commerce/shopping-cli-source.js.map

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

package/dist/commerce/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+/**
+ * CommerceGateway / CommerceClient — the stable boundary between Kiwi and
+ * shopping-cli. All business access goes through this interface; Kiwi never
+ * touches Python modules, SQLite, or platform databases directly.
+ *
+ * Implementations:
+ * - HttpCommerceClient  (commerce/http-client.ts) — shopping-cli 2.x HTTP API
+ * - FakeCommerceClient  (commerce/fake-client.ts) — deterministic in-memory
+ *   LocalMarketplace semantics for tests and offline development
+ */
+import type { CommerceCapabilities, NegotiationDecision, NegotiationSnapshot, PolicyResult, Role } from "../negotiation/types.js";
+/** A conversation message that is waiting for this agent to act. */
+export interface PendingMessage {
+    conversation_id: string;
+    message_id: number;
+    /** e.g. "waiting_merchant" — authoritative routing state. */
+    conversation_status: string;
+    sender_role: Role;
+    preview: string;
+    created_at: string;
+}
+export interface ClaimResult {
+    claimed: boolean;
+    status: string;
+    attempts: number;
+    idempotency_key: string;
+}
+export type ProcessStatus = "processing" | "processed" | "failed" | "abandoned";
+export interface ProcessResult {
+    status: ProcessStatus;
+    message_id: number;
+    last_error?: string;
+}
+export interface CommerceHealth {
+    ok: boolean;
+    service?: string;
+    version?: string;
+    details?: Record<string, unknown>;
+}
+export interface CommerceClient {
+    /** Service liveness/version. Used by `kiwi doctor`. */
+    health(): Promise<CommerceHealth>;
+    /**
+     * Protocol and capability advertisement. Kiwi fails closed when
+     * shopping.negotiation/0.1 or a required capability is missing.
+     */
+    getCapabilities(): Promise<CommerceCapabilities>;
+    /**
+     * Messages routed to this agent and not yet replied to. The gateway
+     * derives role and owner from the Bearer token; the client never sends
+     * and never trusts a claimed role/owner_id.
+     */
+    listPendingMessages(): Promise<PendingMessage[]>;
+    /**
+     * Claim a message for processing. Idempotent: the same idempotency key
+     * returns the same outcome; a non-retryable existing claim returns
+     * claimed=false without an error.
+     */
+    claimMessage(input: {
+        conversation_id: string;
+        message_id: number;
+        idempotency_key: string;
+    }): Promise<ClaimResult>;
+    /**
+     * Authoritative, role-trimmed negotiation snapshot. Only available for a
+     * conversation/message this agent has claimed.
+     */
+    getNegotiationSnapshot(input: {
+        conversation_id: string;
+        message_id: number;
+    }): Promise<NegotiationSnapshot>;
+    /**
+     * The single write intent. The server-side policy gate is authoritative:
+     * identity, turn (next_actor), claim binding, facts, private thresholds
+     * and privacy are all re-checked there.
+     */
+    submitNegotiationDecision(input: {
+        decision: NegotiationDecision;
+        idempotency_key: string;
+    }): Promise<PolicyResult>;
+    completeClaim(input: {
+        message_id: number;
+        idempotency_key: string;
+    }): Promise<ProcessResult>;
+    failClaim(input: {
+        message_id: number;
+        idempotency_key: string;
+        error: string;
+    }): Promise<ProcessResult>;
+    abandonClaim(input: {
+        message_id: number;
+        idempotency_key: string;
+        error: string;
+    }): Promise<ProcessResult>;
+    /**
+     * Liveness for this identity's own processing claims. With message_id,
+     * refreshes only that claim (and only while it is still processing);
+     * without, refreshes all of the actor's processing claims. Never touches
+     * settled or other identities' claims and never revives stale work.
+     */
+    heartbeat(input?: {
+        message_id?: number;
+    }): Promise<HeartbeatResult>;
+    /**
+     * Crash recovery: abandon this identity's OWN stale processing claims
+     * (updated_at older than ttl_seconds). Must run before any heartbeat on a
+     * fresh runtime. Abandoned claims stay reclaimable.
+     */
+    abandonStaleClaims(input?: {
+        ttl_seconds?: number;
+    }): Promise<StaleRecoveryResult>;
+}
+export interface HeartbeatResult {
+    status: string;
+    refreshed: number;
+    at: string;
+}
+export interface StaleRecoveryResult {
+    abandoned: number;
+    message_ids: number[];
+    ttl_seconds: number;
+    at: string;
+}
+export type CommerceErrorKind = "auth" | "not_found" | "conflict" | "rate_limit" | "validation" | "transient";
+export declare class CommerceError extends Error {
+    readonly kind: CommerceErrorKind;
+    readonly status?: number;
+    constructor(kind: CommerceErrorKind, message: string, status?: number);
+}
+/** Idempotency key convention: agent_id + message_id + protocol version. */
+export declare function idempotencyKey(agentId: string, messageId: number, protocolVersion: string): string;

package/dist/commerce/types.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export class CommerceError extends Error {
+    kind;
+    status;
+    constructor(kind, message, status) {
+        super(message);
+        this.name = "CommerceError";
+        this.kind = kind;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+/** Idempotency key convention: agent_id + message_id + protocol version. */
+export function idempotencyKey(agentId, messageId, protocolVersion) {
+    return `${agentId}:${messageId}:${protocolVersion}`;
+}
+//# sourceMappingURL=types.js.map

package/dist/commerce/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/commerce/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiJH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,IAAI,CAAoB;IACxB,MAAM,CAAU;IAEzB,YAAY,IAAuB,EAAE,OAAe,EAAE,MAAe;QACnE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACjD,CAAC;CACF;AAED,4EAA4E;AAC5E,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,SAAiB,EACjB,eAAuB;IAEvB,OAAO,GAAG,OAAO,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;AACtD,CAAC"}

package/dist/config/profile.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 Role } from "../negotiation/types.js";
+export declare const RUNTIME_VERSION = "0.6.0";
+export interface MerchantPolicy {
+    min_unit_price_private?: number;
+    max_auto_discount_percent?: number;
+    inventory_source?: string;
+    quote_ttl_seconds?: number;
+    auto_negotiate?: boolean;
+    human_review_on?: string[];
+}
+/**
+ * Buyer private policy (design §7.2). All fields are required: the local
+ * private-policy gate is a security boundary, so a half-specified policy
+ * fails closed at load time instead of silently disabling checks.
+ *
+ * PRIVATE: max_total_price_private never leaves this process — it is not
+ * sent to the gateway, not logged, and not shown to the counterpart.
+ */
+export interface BuyerPolicy {
+    target_skus: string[];
+    quantity: number;
+    max_total_price_private: number;
+    /** RFC 3339 date-time with an explicit timezone offset (or Z). */
+    acceptable_eta_latest: string;
+    required_after_sales_terms: string[];
+    auto_negotiate: boolean;
+    human_review_on: string[];
+}
+export declare const THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high"];
+export type ProfileThinkingLevel = (typeof THINKING_LEVELS)[number];
+/** API ids supported by the pinned pi-ai 0.83.0 (its KnownApi union). */
+export declare const SUPPORTED_MODEL_APIS: readonly string[];
+/**
+ * Commerce credential scopes (design §15.4). Credentials are held separately
+ * by scope; the model only ever sees tools, never tokens. When a scope has no
+ * credential configured, the corresponding write tools fail closed.
+ */
+export declare const COMMERCE_CREDENTIAL_SCOPES: readonly ["negotiation", "catalog", "inventory"];
+export type CommerceCredentialScope = (typeof COMMERCE_CREDENTIAL_SCOPES)[number];
+export interface AgentProfile {
+    runtime_version: string;
+    protocol_version: string;
+    agent_id: string;
+    role: Role;
+    owner_id: string;
+    commerce: {
+        base_url: string;
+        /** Name of the env var holding the commerce API token (negotiation scope). */
+        token_env: string;
+        backend: "local_marketplace" | "external_platform";
+        /**
+         * Optional per-scope token env refs. `token_env` remains the primary
+         * negotiation credential; catalog/inventory tokens must be configured
+         * separately or the corresponding merchant write tools fail closed.
+         */
+        credentials?: Partial<Record<CommerceCredentialScope, {
+            token_env: string;
+        }>>;
+    };
+    model: {
+        provider: string;
+        model: string;
+        /** Name of the env var holding the model API key. */
+        api_key_env?: string;
+        /** Optional API id override (e.g. "openai-completions"). */
+        api?: string;
+        /** Optional base URL override for OpenAI-compatible endpoints. */
+        base_url?: string;
+        thinking_level?: ProfileThinkingLevel;
+    };
+    runtime: {
+        mode: "once" | "foreground";
+        poll_interval_seconds: number;
+        turn_timeout_seconds: number;
+        max_model_steps: number;
+        max_retries: number;
+    };
+    merchant_policy?: MerchantPolicy;
+    buyer_policy?: BuyerPolicy;
+}
+export declare class ProfileError extends Error {
+    constructor(message: string);
+}
+/** Hard upper bounds for runtime limits. */
+export declare const RUNTIME_LIMITS: {
+    readonly max_model_steps: 20;
+    readonly max_retries: 5;
+    readonly turn_timeout_seconds: 3600;
+    readonly poll_interval_seconds: 3600;
+};
+/** Validate an RFC 3339 timestamp that must carry a timezone. */
+export declare function isRfc3339WithTimezone(value: unknown): value is string;
+/**
+ * Validate a base URL: http(s) only, no embedded credentials, and cleartext
+ * HTTP only for loopback hosts (localhost / 127.0.0.1 / ::1).
+ */
+export declare function assertSecureBaseUrl(value: unknown, field: string, source: string): string;
+/** Load, parse and validate a profile file. Never reads secret env values. */
+export declare function loadProfile(path: string): AgentProfile;
+export declare function validateProfile(data: unknown, source: string): AgentProfile;
+/**
+ * Resolve a secret from an environment variable reference. Throws
+ * ProfileError when unset — callers map this to the config exit code.
+ */
+export declare function resolveSecret(envName: string, what: string): string;
+/** Scan loaded profile data for accidentally inlined secrets. */
+export declare function findInlineSecrets(data: unknown): string[];