@harrylabsj/kiwi 0.6.0

package/dist/handoff/ucp-checkout/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ */
+/**
+ * Kiwi v0.7.0 Transaction Handoff（WP2）— UCP Checkout 协议类型（UCP 2026-04-08
+ * checkout spec family，基线 §3.2 / §43）。
+ *
+ * UCP Checkout REST binding：`{endpoint}/checkout-sessions`（Create/Get/Update/
+ * Complete/Cancel）。响应判别走 `ucp.status`：
+ *   - success：body 就是 checkout 资源本体（含 status/session_id/totals/messages…）；
+ *   - error：无资源本体，只有 messages + continue_url。
+ *
+ * 本模块只建模类型与常量；运行时解析在 parse.ts，网络面在 client.ts。
+ * 零新增依赖。
+ */
+import type { HandoffSession } from "../channel.js";
+/** UCP checkout spec family 日期（§43 pin）。 */
+export declare const UCP_CHECKOUT_SPEC_VERSION: "2026-04-08";
+/** expires_at 缺省值：创建后 6 小时（spec 事实）。 */
+export declare const DEFAULT_EXPIRY_MS: number;
+export declare const UCP_CHECKOUT_STATUSES: readonly ["incomplete", "requires_escalation", "ready_for_complete", "complete_in_progress", "completed", "canceled"];
+export type UcpCheckoutStatus = (typeof UCP_CHECKOUT_STATUSES)[number];
+export declare const UCP_MESSAGE_TYPES: readonly ["error", "warning", "info"];
+export type UcpMessageType = (typeof UCP_MESSAGE_TYPES)[number];
+export declare const UCP_MESSAGE_SEVERITIES: readonly ["recoverable", "requires_buyer_input", "requires_buyer_review", "unrecoverable"];
+export type UcpMessageSeverity = (typeof UCP_MESSAGE_SEVERITIES)[number];
+/** checkout messages[]（type + severity 是算法输入；requires_* 汇聚为 requires_escalation）。 */
+export interface UcpCheckoutMessage {
+    type: UcpMessageType;
+    severity: UcpMessageSeverity;
+    /** 标准错误码（out_of_stock / item_unavailable / payment_failed / eligibility_invalid …）。 */
+    code?: string;
+    message?: string;
+    /** forward-compat：未知字段保留。 */
+    [key: string]: unknown;
+}
+/** links[]（privacy_policy / terms_of_service 等）——合规必需，解析保留。 */
+export interface UcpCheckoutLink {
+    rel: string;
+    href: string;
+    [key: string]: unknown;
+}
+/**
+ * totals：business 权威，platform MUST NOT 自行计算替代；MAY 校验
+ * `非 total 各项之和 == total`（totals.ts）。金额一律整数 minor units。
+ */
+export interface UcpCheckoutTotals {
+    currency: string;
+    items_total?: number;
+    tax?: number;
+    shipping?: number;
+    discount?: number;
+    total: number;
+    [key: string]: unknown;
+}
+export interface UcpCheckoutLineItem {
+    sku: string;
+    quantity: number;
+    unit_price?: {
+        currency: string;
+        amount_minor: number;
+    };
+    [key: string]: unknown;
+}
+/**
+ * UCP checkout 资源本体（success 响应）。payment 对象可选——本实现 complete
+ * 不构造任何支付凭据，只传 authorization 证据引用；payment/links 解析保留。
+ */
+export interface UcpCheckoutSession {
+    ucp: {
+        status: "success";
+        version: string;
+        [key: string]: unknown;
+    };
+    status: UcpCheckoutStatus;
+    session_id: string;
+    expires_at?: string;
+    line_items?: UcpCheckoutLineItem[];
+    totals?: UcpCheckoutTotals;
+    messages?: UcpCheckoutMessage[];
+    continue_url?: string;
+    payment?: Record<string, unknown>;
+    links?: UcpCheckoutLink[];
+    authorization_reference?: string;
+    [key: string]: unknown;
+}
+/** UCP error 响应：无资源本体，只有 messages + continue_url。 */
+export interface UcpCheckoutErrorResponse {
+    ucp: {
+        status: "error";
+        version: string;
+        [key: string]: unknown;
+    };
+    messages: UcpCheckoutMessage[];
+    continue_url?: string;
+    [key: string]: unknown;
+}
+/** 判别联合：`response.ucp.status === "success" | "error"`。 */
+export type UcpCheckoutResponse = UcpCheckoutSession | UcpCheckoutErrorResponse;
+/** fail_closed 结果的结构化上报码（tests 与上层据此分支，不回退到字符串匹配）。 */
+export declare const UCP_CHECKOUT_FAILURE_CODES: readonly ["invalid_package", "invalid_terms", "invalid_quantity", "session_not_found", "session_not_actionable", "session_expired", "not_ready", "gate_denied", "totals_mismatch", "recoverable", "unrecoverable", "unsafe_target", "timeout", "network", "bad_status", "malformed", "cart_not_found", "cart_not_actionable", "cart_capability_unavailable"];
+export type UcpCheckoutFailureCode = (typeof UCP_CHECKOUT_FAILURE_CODES)[number];
+/**
+ * UcpCheckoutChannel 的结构化结果。兼容 HandoffChannel 三形态（HandoffResult），
+ * 每个成员都是对应 HandoffResult 成员的超集：
+ *   ok            —— 操作成功，携带本地 session 投影 + 远端 checkout；
+ *   fail_closed   —— 明确拒绝（retryable:true 表示「改输入重试」，不自动死循环）；
+ *   requires_user —— 需要用户介入外部 checkout（continue_url 指向可信 UI）。
+ */
+export type UcpCheckoutResult = {
+    status: "ok";
+    session_ref: string;
+    session: HandoffSession;
+    continue_url?: string;
+    checkout: UcpCheckoutSession;
+    checkout_status: UcpCheckoutStatus;
+} | {
+    status: "fail_closed";
+    reason: string;
+    messages: UcpCheckoutMessage[];
+    /** 结构化上报码（totals_mismatch / session_expired / unsafe_target …）。 */
+    code?: UcpCheckoutFailureCode;
+    /** true=可改输入后重试（recoverable）；缺省=终态/传输失败，重试无意义。 */
+    retryable?: boolean;
+    checkout_status?: UcpCheckoutStatus;
+    /** 服务器已创建 session 时携带，供上层 updateSession 修正。 */
+    session_ref?: string;
+    checkout?: UcpCheckoutSession;
+} | {
+    status: "requires_user";
+    continue_url?: string;
+    reason: string;
+    messages: UcpCheckoutMessage[];
+    checkout_status?: UcpCheckoutStatus;
+    session_ref?: string;
+    checkout?: UcpCheckoutSession;
+};

package/dist/handoff/ucp-checkout/types.js

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+/** UCP checkout spec family 日期（§43 pin）。 */
+export const UCP_CHECKOUT_SPEC_VERSION = "2026-04-08";
+/** expires_at 缺省值：创建后 6 小时（spec 事实）。 */
+export const DEFAULT_EXPIRY_MS = 6 * 60 * 60 * 1000;
+export const UCP_CHECKOUT_STATUSES = [
+    "incomplete",
+    "requires_escalation",
+    "ready_for_complete",
+    "complete_in_progress",
+    "completed",
+    "canceled",
+];
+export const UCP_MESSAGE_TYPES = ["error", "warning", "info"];
+export const UCP_MESSAGE_SEVERITIES = [
+    "recoverable",
+    "requires_buyer_input",
+    "requires_buyer_review",
+    "unrecoverable",
+];
+/** fail_closed 结果的结构化上报码（tests 与上层据此分支，不回退到字符串匹配）。 */
+export const UCP_CHECKOUT_FAILURE_CODES = [
+    "invalid_package",
+    "invalid_terms",
+    "invalid_quantity",
+    "session_not_found",
+    "session_not_actionable",
+    "session_expired",
+    "not_ready",
+    "gate_denied",
+    "totals_mismatch",
+    "recoverable",
+    "unrecoverable",
+    "unsafe_target",
+    "timeout",
+    "network",
+    "bad_status",
+    "malformed",
+    // cart→checkout 路径的结构化码（cart_id 仅 business profile 宣告 cart capability 时可用）。
+    "cart_not_found",
+    "cart_not_actionable",
+    "cart_capability_unavailable",
+];
+//# sourceMappingURL=types.js.map

package/dist/handoff/ucp-checkout/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/handoff/ucp-checkout/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,4CAA4C;AAC5C,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAqB,CAAC;AAE/D,wCAAwC;AACxC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEpD,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,YAAY;IACZ,qBAAqB;IACrB,oBAAoB;IACpB,sBAAsB;IACtB,WAAW;IACX,UAAU;CACF,CAAC;AAGX,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAU,CAAC;AAGvE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,aAAa;IACb,sBAAsB;IACtB,uBAAuB;IACvB,eAAe;CACP,CAAC;AAwEX,sDAAsD;AACtD,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,iBAAiB;IACjB,eAAe;IACf,kBAAkB;IAClB,mBAAmB;IACnB,wBAAwB;IACxB,iBAAiB;IACjB,WAAW;IACX,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,eAAe;IACf,eAAe;IACf,SAAS;IACT,SAAS;IACT,YAAY;IACZ,WAAW;IACX,4EAA4E;IAC5E,gBAAgB;IAChB,qBAAqB;IACrB,6BAA6B;CACrB,CAAC"}

package/dist/handoff/url-safety.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 interface UrlSafetyOptions {
+    /** merchant 声明域（canonical host）；目的地 host 必须与之同 authority。 */
+    expectedHost?: string;
+    /** 显式 allowlist（host 白名单；配置了 expectedHost 时仍要求命中其一）。 */
+    allowlist?: readonly string[];
+    /** 允许 http（非 https）？缺省 false；localhost 始终允许 http。 */
+    allowHttp?: boolean;
+    /** 最大重定向次数（缺省 5；超过 → fail-closed）。 */
+    maxRedirects?: number;
+    /** 注入 fetch（测试）。 */
+    fetchImpl?: typeof fetch;
+    /** 请求超时 ms（缺省 15000）。 */
+    timeoutMs?: number;
+    /** SSRF DNS 复查的解析函数（缺省 node:dns lookup；受控/测试环境注入用）。 */
+    resolveIp?: (hostname: string) => Promise<string[]>;
+    /** 跳过 SSRF DNS 复查（仅测试/受控环境；生产缺省 false）。 */
+    skipDnsCheck?: boolean;
+}
+export interface SafeDestinationUrl {
+    /** 展示给用户的最终 URL（重定向解析后）。 */
+    finalUrl: string;
+    /** 重定向链（原始 → 最终）。 */
+    redirects: readonly string[];
+}
+/**
+ * 校验并解析外部目的地 URL。重定向链上的每一跳都重新过 scheme / host /
+ * SSRF 检查（防跳转到 unsafe 目标）。返回最终 URL 供展示。
+ */
+export declare function validateExternalDestinationUrl(value: string, options?: UrlSafetyOptions): Promise<SafeDestinationUrl>;

package/dist/handoff/url-safety.js

@@ -0,0 +1,121 @@
+/**
+ * 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.
+ */
+/**
+ * KTH/0.1 目的地 URL 安全（rev0.3 §11.2；架构 rev1.4.1 §36-26/27）。
+ *
+ * 检查：
+ *   - scheme 白名单：https 默认；http 仅 localhost / 显式配置允许；
+ *     file:/javascript:/data: 等一律拒绝（fail-closed）；
+ *   - userinfo 拒绝（防钓鱼 URL 伪装 authority）；
+ *   - redirect 限制：fetch redirect:"manual" 跟随 ≤ maxRedirects（默认 5），
+ *     每次重定向后重新校验 scheme/host（防跳转到 unsafe scheme）；
+ *   - anti-phishing / allowlist：host 必须与 merchant 声明域一致（或命中
+ *     显式 allowlist）；拒绝 IP 直连（复用 a2a client 的 SSRF 策略）；
+ *   - 返回最终 URL（供用户展示，完成定义 #17）。
+ */
+import { assertResolvableTargetUrl, assertSafeTargetUrl } from "../a2a/client/url-policy.js";
+import { CommerceError } from "../commerce/data-source.js";
+const DEFAULT_MAX_REDIRECTS = 5;
+const DEFAULT_TIMEOUT_MS = 15_000;
+function assertScheme(url, options) {
+    if (url.protocol === "https:")
+        return;
+    if (url.protocol === "http:" && (options.allowHttp === true || isLocalHost(url.hostname)))
+        return;
+    throw new CommerceError("invalid_input", `unsafe destination scheme "${url.protocol}" (HTTPS required; http only for localhost or explicit allowHttp)`);
+}
+function isLocalHost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
+/** host 是否命中 allowlist / expectedHost（同 authority）。 */
+function hostAllowed(hostname, options) {
+    if (options.expectedHost !== undefined && options.expectedHost === hostname)
+        return true;
+    if (options.allowlist !== undefined && options.allowlist.includes(hostname))
+        return true;
+    return false;
+}
+/**
+ * 校验并解析外部目的地 URL。重定向链上的每一跳都重新过 scheme / host /
+ * SSRF 检查（防跳转到 unsafe 目标）。返回最终 URL 供展示。
+ */
+export async function validateExternalDestinationUrl(value, options = {}) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const redirects = [];
+    let current = value;
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+        // 首跳必须命中 expectedHost / allowlist；重定向跳转目标同规则
+        // （SSRF 策略在 assertSafeTargetUrl：http(s) only / 无 userinfo /
+        // 保留网段拒绝 / loopback http 例外）。
+        const parsed = assertSafeTargetUrl(current);
+        assertScheme(parsed, options);
+        if (!hostAllowed(parsed.hostname, options)) {
+            throw new CommerceError("invalid_input", `destination host "${parsed.hostname}" is not allowed (expected ${options.expectedHost ?? "allowlist"})`);
+        }
+        // 请求前 DNS 复查：主机名解析的每个 IP 过保留网段判定（防 rebinding）。
+        // 此前只对字面 IP 生效——expectedHost 命中但解析到 169.254.169.254 等
+        // 内网地址的主机名会真实发出探测。
+        try {
+            await assertResolvableTargetUrl(parsed, {
+                skipDnsCheck: options.skipDnsCheck,
+                resolveIp: options.resolveIp,
+            });
+        }
+        catch (err) {
+            throw new CommerceError("invalid_input", `destination DNS rejected by safety policy: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            // HEAD 探测重定向；2xx 即终点（不 HEAD 的服务器按不可达拒绝，绝不把
+            // 404/500/403 死链当"已验证目的地"交付给用户展示）。
+            response = await fetchImpl(current, {
+                method: "HEAD",
+                redirect: "manual",
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const name = err?.name;
+            throw new CommerceError("request_failed", name === "AbortError"
+                ? `destination probe timed out after ${timeoutMs}ms: ${current}`
+                : `destination probe failed: ${current} (${err instanceof Error ? err.message : String(err)})`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const location = response.headers.get("location");
+        if (location === null) {
+            if (response.status < 200 || response.status >= 300) {
+                throw new CommerceError("request_failed", `destination probe returned HTTP ${response.status} (not a reachable 2xx endpoint): ${current}`);
+            }
+            return { finalUrl: current, redirects };
+        }
+        if (response.status < 300 || response.status >= 400) {
+            throw new CommerceError("request_failed", `destination returned a redirect Location with non-3xx status (HTTP ${response.status}): ${current}`);
+        }
+        if (hop === maxRedirects) {
+            throw new CommerceError("invalid_input", `destination exceeded max redirects (${maxRedirects})`);
+        }
+        redirects.push(current);
+        current = new URL(location, current).href;
+    }
+    throw new CommerceError("invalid_input", `destination exceeded max redirects (${maxRedirects})`);
+}
+//# sourceMappingURL=url-safety.js.map

package/dist/handoff/url-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-safety.js","sourceRoot":"","sources":["../../src/handoff/url-safety.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC7F,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AA4B3D,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAChC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,SAAS,YAAY,CAAC,GAAQ,EAAE,OAAyB;IACvD,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO;IACtC,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,KAAK,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAAE,OAAO;IAClG,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,8BAA8B,GAAG,CAAC,QAAQ,mEAAmE,CAC9G,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,QAAgB;IACnC,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,WAAW,IAAI,QAAQ,KAAK,KAAK,CAAC;AACpF,CAAC;AAED,uDAAuD;AACvD,SAAS,WAAW,CAAC,QAAgB,EAAE,OAAyB;IAC9D,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,IAAI,OAAO,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzF,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACzF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,KAAa,EACb,UAA4B,EAAE;IAE9B,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACxD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,qBAAqB,CAAC;IACnE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAE1D,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,IAAI,YAAY,EAAE,GAAG,EAAE,EAAE,CAAC;QAC7C,6CAA6C;QAC7C,4DAA4D;QAC5D,8BAA8B;QAC9B,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAC5C,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,qBAAqB,MAAM,CAAC,QAAQ,8BAA8B,OAAO,CAAC,YAAY,IAAI,WAAW,GAAG,CACzG,CAAC;QACJ,CAAC;QACD,+CAA+C;QAC/C,sDAAsD;QACtD,mBAAmB;QACnB,IAAI,CAAC;YACH,MAAM,yBAAyB,CAAC,MAAM,EAAE;gBACtC,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,8CAA8C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACjG,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,2CAA2C;YAC3C,mCAAmC;YACnC,QAAQ,GAAG,MAAM,SAAS,CAAC,OAAO,EAAE;gBAClC,MAAM,EAAE,MAAM;gBACd,QAAQ,EAAE,QAAQ;gBAClB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,GAAI,GAAgC,EAAE,IAAI,CAAC;YACrD,MAAM,IAAI,aAAa,CACrB,gBAAgB,EAChB,IAAI,KAAK,YAAY;gBACnB,CAAC,CAAC,qCAAqC,SAAS,OAAO,OAAO,EAAE;gBAChE,CAAC,CAAC,6BAA6B,OAAO,KAAK,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CACjG,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAClD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;gBACpD,MAAM,IAAI,aAAa,CACrB,gBAAgB,EAChB,mCAAmC,QAAQ,CAAC,MAAM,oCAAoC,OAAO,EAAE,CAChG,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,GAAG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YACpD,MAAM,IAAI,aAAa,CACrB,gBAAgB,EAChB,sEAAsE,QAAQ,CAAC,MAAM,MAAM,OAAO,EAAE,CACrG,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,uCAAuC,YAAY,GAAG,CACvD,CAAC;QACJ,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxB,OAAO,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC;IAC5C,CAAC;IACD,MAAM,IAAI,aAAa,CACrB,eAAe,EACf,uCAAuC,YAAY,GAAG,CACvD,CAAC;AACJ,CAAC"}

package/dist/i18n.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+/**
+ * 最小 i18n：自然语言报告（如 /negotiate 总结）跟随用户语言，不写死中文。
+ *
+ * 语言判定：
+ *   1. `KIWI_LANG` 显式覆盖（zh / en）；
+ *   2. 否则读 `LANG` / `LC_ALL`：`zh*` → 中文，其余 → 英文（缺省）。
+ */
+export type KiwiLocale = "zh" | "en";
+export declare function detectLocale(): KiwiLocale;

package/dist/i18n.js

@@ -0,0 +1,27 @@
+/**
+ * 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 function detectLocale() {
+    const explicit = process.env.KIWI_LANG?.trim().toLowerCase();
+    if (explicit === "zh" || explicit === "zh-cn" || explicit === "zh_cn" || explicit === "zh-hans") {
+        return "zh";
+    }
+    if (explicit === "en" || explicit === "en-us" || explicit === "en_us") {
+        return "en";
+    }
+    const lang = (process.env.LANG ?? process.env.LC_ALL ?? "").toLowerCase();
+    return lang.startsWith("zh") ? "zh" : "en";
+}
+//# sourceMappingURL=i18n.js.map

package/dist/i18n.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.js","sourceRoot":"","sources":["../src/i18n.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,MAAM,UAAU,YAAY;IAC1B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7D,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACtE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1E,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/negotiation/action-candidate.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 { DecisionAction, NegotiationDecision } from "./types.js";
+export declare const ACTION_CANDIDATE_KINDS: readonly ["negotiation"];
+export type ActionCandidateKind = (typeof ACTION_CANDIDATE_KINDS)[number];
+/** Risk levels bound to a candidate (mirrors the operator's strategy risk). */
+export declare const CANDIDATE_RISK_LEVELS: readonly ["ok", "confirm", "blocked"];
+export type CandidateRiskLevel = (typeof CANDIDATE_RISK_LEVELS)[number];
+export interface CandidateRisk {
+    level: CandidateRiskLevel;
+    reason: string;
+}
+/** Base: a suggested, not-yet-executed external side-effectful action. */
+export interface ActionCandidate {
+    /** Stable identifier; never reused for a different action. */
+    candidate_id: string;
+    /** Subtype discriminant for narrowing across candidate families. */
+    kind: ActionCandidateKind;
+    /** The proposed external side-effect action, as a stable action token. */
+    action: string;
+    /** The payload the action would be executed with. */
+    payload: unknown;
+}
+/** Negotiation action candidate — an ActionCandidate bound to a negotiation. */
+export interface NegotiationActionCandidate extends ActionCandidate {
+    kind: "negotiation";
+    action: DecisionAction;
+    payload: NegotiationDecision;
+    /** The business negotiation this candidate belongs to (v0.2 conversation_id). */
+    negotiation_id: string;
+    /** RFC 8785 JCS + SHA-256 content digest of the bound candidate fields. */
+    candidate_digest: string;
+    /** Remote revision the candidate was generated against (§19 re-validation). */
+    expected_remote_revision: string;
+    /** Policy version that produced/approved this candidate. */
+    policy_version: string;
+    /** Counterparty identity the candidate targets, as observed by us. */
+    counterparty_identity: string;
+    /** Public draft shown to the counterpart (never private reasoning). */
+    public_message: string;
+    reason_codes: string[];
+    risk: CandidateRisk;
+}
+/**
+ * v0.2 compatibility term (docs §6/§7.3). The v0.2 operator control plane's
+ * `Candidate` (`src/operator/types.ts`) satisfies this shape. Only the bridge
+ * below still names it; new code consumes NegotiationActionCandidate.
+ */
+export interface DecisionCandidate {
+    candidate_id: string;
+    binding: {
+        conversation_id: string;
+        message_id: number;
+    };
+    decision: NegotiationDecision;
+    created_at: string;
+}
+/** Context bindings the v0.2 DecisionCandidate does not carry itself. */
+export interface NegotiationActionCandidateContext {
+    expected_remote_revision: string;
+    policy_version: string;
+    counterparty_identity: string;
+    risk: CandidateRisk;
+}
+export declare class CandidateAdapterError extends Error {
+    readonly code: "missing_field" | "invalid_field";
+    readonly field?: string;
+    constructor(code: CandidateAdapterError["code"], message: string, field?: string);
+}
+/**
+ * Bridge the v0.2 DecisionCandidate into the v0.4 NegotiationActionCandidate.
+ * Missing or malformed binding fields fail closed (CandidateAdapterError); the
+ * digest is always recomputed from the mapped fields, never trusted from input.
+ */
+export declare function toNegotiationActionCandidate(decision: DecisionCandidate, context: NegotiationActionCandidateContext): NegotiationActionCandidate;
+/**
+ * RFC 8785 JCS + SHA-256 digest over the bound candidate fields (docs §17).
+ * `candidate_digest` itself is excluded — content addressing never hashes its
+ * own envelope. Equal candidates always produce the same digest; any bound
+ * field change produces a different one.
+ */
+export declare function candidateDigest(input: Omit<NegotiationActionCandidate, "candidate_digest">): string;
+/** Recomputed-digest check; false means the candidate is stale (§19). */
+export declare function verifyCandidateDigest(candidate: NegotiationActionCandidate): boolean;