@harrylabsj/kiwi 0.6.0

package/dist/counterparty/channel.d.ts

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+/**
+ * CounterpartyChannel 唯一接口（基线 §5 / §33 / §38 推荐结构）。
+ *
+ * 职责边界（§33）：
+ *   - AgentDiscovery 负责：domain → Agent Card → capability intersection →
+ *     identity bootstrap → channel candidates；
+ *   - CounterpartyChannel 负责：open / send / getState / subscribe / close。
+ *
+ * 本模块是三条通道（a2a-direct / shopping-cli-hosted / platform-api）与上层
+ * （recovery、未来 Negotiation Engine）之间的**唯一**接缝。WP3 recovery 的
+ * `CounterpartyChannel`（identity+url 二元组）在本 WP 收敛为此处定义的单接口，
+ * 不再有第二套契约。
+ *
+ * 不变量（基线 §4.6 Fail Closed / §36-21）：
+ *   - open 失败 / send 失败绝不由通道内部降级到权限更宽的通道；候选选择是
+ *     确定性的一次性决策（selectChannelCandidate），没有自动重试队列；
+ *   - 未知状态 / 校验失败一律抛 ChannelError（fail-closed），不静默容错。
+ */
+import type { A2ATask, A2ATaskState } from "../a2a/client/index.js";
+import type { NegotiationEnvelope } from "../negotiation/domain/envelope.js";
+import type { PolicyResult } from "../negotiation/types.js";
+import type { AgentCard } from "../discovery/agent-card/index.js";
+import type { CapabilityIntersection } from "../discovery/capability/index.js";
+import type { UcpIntersectionView } from "../discovery/ucp/intersect.js";
+import type { UcpProfile } from "../discovery/ucp/types.js";
+/** 通道种类（基线 §5 三个实现）。 */
+export type ChannelKind = "a2a-direct" | "shopping-cli-hosted" | "platform-api";
+/**
+ * 远端通道引用：negotiation + 该通道家族自己的锚点。
+ *
+ * direct 用 context_id/task_id；hosted 用 conversation_id/message_id。两组字段
+ * 分属两个通道家族，互不冲突。taskId 只是 transport/session 状态，不得替代
+ * negotiation_id（基线 §9.5）。
+ */
+export interface RemoteRef {
+    negotiation_id: string;
+    /** A2A contextId（direct，opaque，§9.2）。 */
+    context_id?: string;
+    /** A2A taskId（direct，§9.5）。 */
+    task_id?: string;
+    /** shopping-cli conversation_id（hosted）。 */
+    conversation_id?: string;
+    /** shopping-cli message_id（hosted）。 */
+    message_id?: number;
+}
+/** 打开通道的输入。open 把通道绑定到一个 negotiation 实例。 */
+export interface ChannelOpenInput {
+    negotiation_id: string;
+    /** 本方（Kiwi）身份 —— Ledger identity 的 sender 侧。 */
+    sender_identity: string;
+    /** 对端身份 —— 协议幂等键的 counterparty 侧。 */
+    identity: string;
+    /** 初始远端锚点（可选；direct 首次 send 后获得 taskId；hosted 打开即绑定会话）。 */
+    remote?: {
+        context_id?: string;
+        task_id?: string;
+        conversation_id?: string;
+        message_id?: number;
+    };
+    /** 打开/请求超时 ms。 */
+    timeoutMs?: number;
+}
+/** send 的输入：KNP envelope + 目标引用。 */
+export interface ChannelSendInput {
+    envelope: NegotiationEnvelope;
+    ref?: RemoteRef;
+}
+/**
+ * send 结果。成功返回结构化结果；硬失败（网络 / 校验 / 权限）一律抛 ChannelError。
+ * direct 通道带 `task`；hosted 通道带 `policy`。
+ */
+export interface ChannelSendResult {
+    channel: ChannelKind;
+    /** 发送后应更新的远端锚点。 */
+    ref: RemoteRef;
+    /** direct：message/send 的远端任务。 */
+    task?: A2ATask;
+    /** hosted：策略结果（accepted / rejected_retryable / human_required）。 */
+    policy?: PolicyResult;
+    /** 幂等重放：true 表示未重复发送，返回先前结果（§17 / §20）。 */
+    replayed?: boolean;
+}
+/**
+ * 远端稳定观察点（getState）。`state` 是权威状态值：
+ *   - direct：A2A task state（§18.3）；
+ *   - hosted：shopping-cli conversation status（§21 Authority Model：
+ *     authoritative snapshot > local cache > reasoning state）。
+ */
+export interface RemoteState {
+    channel: ChannelKind;
+    /** 权威状态值。 */
+    state: string;
+    /** 是否为稳定观察点（终态或等待输入）。 */
+    stable: boolean;
+    /** direct：A2A Task 视图。 */
+    task?: A2ATask;
+    /** hosted：shopping-cli 权威快照（§21）。 */
+    snapshot?: import("../negotiation/types.js").NegotiationSnapshot;
+    /** 远端可见 messageId 集合（recovery 比对 acknowledged messages）。 */
+    message_ids: string[];
+    observed_at: string;
+}
+export type RemoteEventKind = "state_changed" | "message_received" | "error";
+/** 异步推送/轮询事件（§33 subscribe）。 */
+export interface RemoteEvent {
+    channel: ChannelKind;
+    kind: RemoteEventKind;
+    ref: RemoteRef;
+    state?: RemoteState;
+    message_id?: string;
+    error?: ChannelError;
+}
+export type ChannelEventHandler = (event: RemoteEvent) => void | Promise<void>;
+export type Unsubscribe = () => void | Promise<void>;
+/** 通道打开后的操作面。open 后持有该 handle 执行 send/getState/subscribe/close。 */
+export interface ChannelHandle {
+    readonly kind: ChannelKind;
+    /** 对端身份（open 时绑定）。 */
+    readonly identity: string;
+    send(input: ChannelSendInput): Promise<ChannelSendResult>;
+    getState(ref: RemoteRef): Promise<RemoteState>;
+    /** 无 subscribe 的通道通过 getState 轮询（§33）。 */
+    subscribe?(ref: RemoteRef, handler: ChannelEventHandler): Promise<Unsubscribe>;
+    close(): Promise<void>;
+}
+/** CounterpartyChannel 工厂接口：open 打开一条绑定到 negotiation 的通道。 */
+export interface CounterpartyChannel {
+    readonly kind: ChannelKind;
+    open(input: ChannelOpenInput): Promise<ChannelHandle>;
+}
+export declare const CHANNEL_ERROR_CODES: readonly ["no_channel_candidate", "channel_closed", "invalid_envelope", "idempotency_conflict", "send_failed", "get_state_failed", "unsupported_action", "commerce_client_not_configured", "platform_not_configured", "not_implemented"];
+export type ChannelErrorCode = (typeof CHANNEL_ERROR_CODES)[number];
+/** 通道层失败。带通道 kind 与协议错误码；fail-closed，绝不静默降级。 */
+export declare class ChannelError extends Error {
+    readonly channel: ChannelKind;
+    readonly code: ChannelErrorCode;
+    constructor(channel: ChannelKind, code: ChannelErrorCode, message: string);
+}
+/**
+ * 通道候选（§33 AgentDiscovery 产出）。数组顺序即优先序：
+ * a2a-direct → shopping-cli-hosted → platform-api。每个候选携带构造所需的最小配置。
+ */
+export interface ChannelCandidate {
+    kind: ChannelKind;
+    /** a2a-direct：capability intersection 选中的远端 endpoint URL。 */
+    url?: string;
+    /** shopping-cli-hosted：本地配置的 commerce 服务标识（供 deps.commerce 解析）。 */
+    config_id?: string;
+    /** platform-api：平台凭证引用（fail-closed，必须显式配置）。 */
+    credential_ref?: string;
+}
+/**
+ * 解析出的对端通道档案（§33 AgentDiscovery 第 1–5 步的产物）。
+ * resolveCounterparty（recovery）/ 未来 Negotiation Engine 只依赖此档案 + open。
+ */
+export interface CounterpartyProfile {
+    /** 对端身份（协议幂等键 counterparty 侧；来自 Agent Card provider/name）。 */
+    identity: string;
+    /** 解析来源：`domain:<host>` 或 `card:<url>`。 */
+    source: string;
+    /** 拉取并校验后的 Agent Card（结构校验 + secret 扫描，不变量 24）。 */
+    agent_card: AgentCard;
+    /** 双方 capability intersection（§33）。 */
+    intersection: CapabilityIntersection;
+    /** 按优先序排列的通道候选。 */
+    channel_candidates: ChannelCandidate[];
+    /**
+     * WP3：双方 UCP capability intersection（§3.2 / §25），与 A2A binding
+     * `intersection` 两个维度并存。UCP 优先路径成功且配置了 platform 侧
+     * localProfile 时存在。
+     */
+    ucp_intersection?: UcpIntersectionView;
+    /** WP3：解析出的对端 UCP profile（UCP 优先路径成功时存在）。 */
+    ucp_profile?: UcpProfile;
+    /** WP3：UCP 优先路径失败时的回退原因（已回退到 well-known Agent Card）。 */
+    ucp_fallback_reason?: string;
+}
+/**
+ * 确定性选择首选候选（§33 / 不变量 21）：按 direct → hosted → platform 的固定
+ * 顺序取第一个可用候选。这是**一次性**决策——调用方不得在后续失败时自动退到
+ * 更宽的候选（不变量 21）。
+ */
+export declare function selectChannelCandidate(profile: CounterpartyProfile): ChannelCandidate | null;
+/** 便捷断言：把 A2A task 状态归一化为 RemoteState（direct 通道内部用）。 */
+export declare function isStableTaskState(state: A2ATaskState): boolean;

package/dist/counterparty/channel.js

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+/** 通道候选的确定性优先序（§33：A2A 可用 → direct；否则 hosted；都没有 fail-closed）。 */
+const CHANNEL_PREFERENCE = ["a2a-direct", "shopping-cli-hosted", "platform-api"];
+// ---------------------------------------------------------------------------
+// ChannelError
+// ---------------------------------------------------------------------------
+export const CHANNEL_ERROR_CODES = [
+    "no_channel_candidate",
+    "channel_closed",
+    "invalid_envelope",
+    "idempotency_conflict",
+    "send_failed",
+    "get_state_failed",
+    "unsupported_action",
+    "commerce_client_not_configured",
+    "platform_not_configured",
+    "not_implemented",
+];
+/** 通道层失败。带通道 kind 与协议错误码；fail-closed，绝不静默降级。 */
+export class ChannelError extends Error {
+    channel;
+    code;
+    constructor(channel, code, message) {
+        super(message);
+        this.name = "ChannelError";
+        this.channel = channel;
+        this.code = code;
+    }
+}
+/**
+ * 确定性选择首选候选（§33 / 不变量 21）：按 direct → hosted → platform 的固定
+ * 顺序取第一个可用候选。这是**一次性**决策——调用方不得在后续失败时自动退到
+ * 更宽的候选（不变量 21）。
+ */
+export function selectChannelCandidate(profile) {
+    const rank = new Map(CHANNEL_PREFERENCE.map((k, i) => [k, i]));
+    const ordered = [...profile.channel_candidates].sort((a, b) => (rank.get(a.kind) ?? Number.POSITIVE_INFINITY) - (rank.get(b.kind) ?? Number.POSITIVE_INFINITY));
+    return ordered[0] ?? null;
+}
+/** 便捷断言：把 A2A task 状态归一化为 RemoteState（direct 通道内部用）。 */
+export function isStableTaskState(state) {
+    return (state === "completed" ||
+        state === "canceled" ||
+        state === "failed" ||
+        state === "input-required");
+}
+//# sourceMappingURL=channel.js.map

package/dist/counterparty/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/counterparty/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAgCH,kEAAkE;AAClE,MAAM,kBAAkB,GAA2B,CAAC,YAAY,EAAE,qBAAqB,EAAE,cAAc,CAAC,CAAC;AAmHzG,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,sBAAsB;IACtB,gBAAgB;IAChB,kBAAkB;IAClB,sBAAsB;IACtB,aAAa;IACb,kBAAkB;IAClB,oBAAoB;IACpB,gCAAgC;IAChC,yBAAyB;IACzB,iBAAiB;CACT,CAAC;AAGX,gDAAgD;AAChD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,OAAO,CAAc;IACrB,IAAI,CAAmB;IAChC,YAAY,OAAoB,EAAE,IAAsB,EAAE,OAAe;QACvE,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AA+CD;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA4B;IACjE,MAAM,IAAI,GAAG,IAAI,GAAG,CAAsB,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAClD,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,iBAAiB,CAAC,CAC1G,CAAC;IACF,OAAO,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,iBAAiB,CAAC,KAAmB;IACnD,OAAO,CACL,KAAK,KAAK,WAAW;QACrB,KAAK,KAAK,UAAU;QACpB,KAAK,KAAK,QAAQ;QAClB,KAAK,KAAK,gBAAgB,CAC3B,CAAC;AACJ,CAAC"}

package/dist/counterparty/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * counterparty — CounterpartyChannel 唯一接口 + 三个实现（基线 §5 / §33 / §38）。
+ */
+export { CHANNEL_ERROR_CODES, ChannelError, isStableTaskState, selectChannelCandidate, } from "./channel.js";
+export type { ChannelCandidate, ChannelErrorCode, ChannelEventHandler, ChannelHandle, ChannelKind, ChannelOpenInput, ChannelSendInput, ChannelSendResult, CounterpartyChannel, CounterpartyProfile, RemoteEvent, RemoteEventKind, RemoteRef, RemoteState, Unsubscribe, } from "./channel.js";
+export { A2ADirectChannel } from "./a2a-direct/index.js";
+export type { A2ADirectChannelOptions } from "./a2a-direct/index.js";
+export { ShoppingCliHostedChannel } from "./shopping-cli-hosted/index.js";
+export type { ShoppingCliHostedChannelOptions } from "./shopping-cli-hosted/index.js";
+export { PlatformApiChannel } from "./platform-api/index.js";
+export type { PlatformApiChannelOptions } from "./platform-api/index.js";
+export { openChannel } from "./registry.js";
+export type { ChannelRuntimeDeps } from "./registry.js";

package/dist/counterparty/index.js

@@ -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.
+ */
+/**
+ * counterparty — CounterpartyChannel 唯一接口 + 三个实现（基线 §5 / §33 / §38）。
+ */
+export { CHANNEL_ERROR_CODES, ChannelError, isStableTaskState, selectChannelCandidate, } from "./channel.js";
+export { A2ADirectChannel } from "./a2a-direct/index.js";
+export { ShoppingCliHostedChannel } from "./shopping-cli-hosted/index.js";
+export { PlatformApiChannel } from "./platform-api/index.js";
+export { openChannel } from "./registry.js";
+//# sourceMappingURL=index.js.map

package/dist/counterparty/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/counterparty/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;GAEG;AAEH,OAAO,EACL,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AAmBtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAG1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/counterparty/platform-api/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+/**
+ * PlatformApiChannel — 平台 API 通道占位（基线 §5 / §33）。
+ *
+ * 本 WP 只落地接口占位 + fail-closed 默认实现（基线 §4.6 / §36）：
+ *
+ *   - 未配置平台凭证（configured=false）→ open 抛 ChannelError("platform_not_configured")，
+ *     绝不静默降级到 hosted/direct（不变量 21）；
+ *   - 已配置但实现尚未接线（未来 WP）→ send/getState 抛 ChannelError("not_implemented")。
+ *
+ * 平台 API 是权限最宽的通道（可能触碰平台侧订单/支付面），因此 fail-closed
+ * 语义最严格：宁可拒绝，不猜、不降级。
+ */
+import { type ChannelHandle, type ChannelOpenInput, type CounterpartyChannel } from "../channel.js";
+export interface PlatformApiChannelOptions {
+    /** 是否已配置平台凭证。缺省 false（fail-closed）。 */
+    configured?: boolean;
+    /** 平台凭证引用（仅元数据，不承载 secret；不变量 24）。 */
+    credentialRef?: string;
+}
+export declare class PlatformApiChannel implements CounterpartyChannel {
+    readonly kind: "platform-api";
+    private readonly configured;
+    private readonly credentialRef?;
+    constructor(options?: PlatformApiChannelOptions);
+    open(input: ChannelOpenInput): Promise<ChannelHandle>;
+}

package/dist/counterparty/platform-api/index.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * PlatformApiChannel — 平台 API 通道占位（基线 §5 / §33）。
+ *
+ * 本 WP 只落地接口占位 + fail-closed 默认实现（基线 §4.6 / §36）：
+ *
+ *   - 未配置平台凭证（configured=false）→ open 抛 ChannelError("platform_not_configured")，
+ *     绝不静默降级到 hosted/direct（不变量 21）；
+ *   - 已配置但实现尚未接线（未来 WP）→ send/getState 抛 ChannelError("not_implemented")。
+ *
+ * 平台 API 是权限最宽的通道（可能触碰平台侧订单/支付面），因此 fail-closed
+ * 语义最严格：宁可拒绝，不猜、不降级。
+ */
+import { ChannelError, } from "../channel.js";
+export class PlatformApiChannel {
+    kind = "platform-api";
+    configured;
+    credentialRef;
+    constructor(options = {}) {
+        this.configured = options.configured ?? false;
+        this.credentialRef = options.credentialRef;
+    }
+    async open(input) {
+        if (!this.configured) {
+            throw new ChannelError("platform-api", "platform_not_configured", "platform-api channel is not configured (no platform credentials); refusing to open (fail-closed, no silent downgrade)");
+        }
+        return new PlatformApiHandle(input.identity, this.credentialRef);
+    }
+}
+class PlatformApiHandle {
+    kind = "platform-api";
+    identity;
+    credentialRef;
+    constructor(identity, credentialRef) {
+        this.identity = identity;
+        this.credentialRef = credentialRef;
+    }
+    notImplemented() {
+        return new ChannelError("platform-api", "not_implemented", `platform-api integration is not implemented (credential_ref=${this.credentialRef ?? "none"}); fail-closed`);
+    }
+    async send() {
+        throw this.notImplemented();
+    }
+    async getState() {
+        throw this.notImplemented();
+    }
+    async close() {
+        // 占位：无资源需释放。
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/counterparty/platform-api/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/counterparty/platform-api/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,YAAY,GAIb,MAAM,eAAe,CAAC;AASvB,MAAM,OAAO,kBAAkB;IACpB,IAAI,GAAG,cAAuB,CAAC;IACvB,UAAU,CAAU;IACpB,aAAa,CAAU;IAExC,YAAY,UAAqC,EAAE;QACjD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,KAAK,CAAC;QAC9C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;IAC7C,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAuB;QAChC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,MAAM,IAAI,YAAY,CACpB,cAAc,EACd,yBAAyB,EACzB,uHAAuH,CACxH,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,iBAAiB,CAAC,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IACnE,CAAC;CACF;AAED,MAAM,iBAAiB;IACZ,IAAI,GAAG,cAAuB,CAAC;IAC/B,QAAQ,CAAS;IACT,aAAa,CAAU;IAExC,YAAY,QAAgB,EAAE,aAAsB;QAClD,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACrC,CAAC;IAEO,cAAc;QACpB,OAAO,IAAI,YAAY,CACrB,cAAc,EACd,iBAAiB,EACjB,+DAA+D,IAAI,CAAC,aAAa,IAAI,MAAM,gBAAgB,CAC5G,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;IAC9B,CAAC;IAED,KAAK,CAAC,KAAK;QACT,aAAa;IACf,CAAC;CACF"}

package/dist/counterparty/registry.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.
+ */
+/**
+ * CounterpartyChannel 注册/装配：CounterpartyProfile → 具体通道实例。
+ *
+ * 候选选择是一次性确定性决策（selectChannelCandidate，§33）：direct → hosted →
+ * platform。**不提供失败后自动退到更宽候选的机制**（不变量 21）——一旦选定
+ * direct，其 send/getState 失败就向上抛 ChannelError，绝不静默降级。
+ */
+import type { CommerceClient } from "../commerce/types.js";
+import type { IdempotencyStore } from "../negotiation/idempotency/index.js";
+import type { LedgerStore } from "../negotiation/ledger/index.js";
+import { type ChannelHandle, type ChannelOpenInput, type CounterpartyProfile } from "./channel.js";
+/** 装配通道所需的运行时依赖。 */
+export interface ChannelRuntimeDeps {
+    ledger?: LedgerStore;
+    idempotency?: IdempotencyStore;
+    /** hosted commerce client 提供者（按 config_id 解析）；返回 null 表示未配置。 */
+    commerce?: (configId: string | undefined) => CommerceClient | null;
+    /** platform 凭证状态（fail-closed）。 */
+    platform?: {
+        configured: boolean;
+        credentialRef?: string;
+    };
+    now?: () => string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * 从 profile 打开一条通道（确定性选择首选候选，失败不降级）。
+ *
+ * 失败路径抛 ChannelError：
+ *   - 无可用候选 → no_channel_candidate；
+ *   - a2a-direct 候选缺 url → no_channel_candidate；
+ *   - hosted 候选但未配置 commerce client → commerce_client_not_configured；
+ *   - platform 候选但未配置凭证 → platform_not_configured。
+ */
+export declare function openChannel(profile: CounterpartyProfile, deps: ChannelRuntimeDeps, input: ChannelOpenInput): Promise<ChannelHandle>;

package/dist/counterparty/registry.js

@@ -0,0 +1,71 @@
+/**
+ * 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 { ChannelError, selectChannelCandidate, } from "./channel.js";
+import { A2ADirectChannel } from "./a2a-direct/index.js";
+import { ShoppingCliHostedChannel } from "./shopping-cli-hosted/index.js";
+import { PlatformApiChannel } from "./platform-api/index.js";
+/**
+ * 从 profile 打开一条通道（确定性选择首选候选，失败不降级）。
+ *
+ * 失败路径抛 ChannelError：
+ *   - 无可用候选 → no_channel_candidate；
+ *   - a2a-direct 候选缺 url → no_channel_candidate；
+ *   - hosted 候选但未配置 commerce client → commerce_client_not_configured；
+ *   - platform 候选但未配置凭证 → platform_not_configured。
+ */
+export async function openChannel(profile, deps, input) {
+    const candidate = selectChannelCandidate(profile);
+    if (candidate === null) {
+        throw new ChannelError("platform-api", "no_channel_candidate", `no usable channel candidate for counterparty ${profile.identity}`);
+    }
+    switch (candidate.kind) {
+        case "a2a-direct": {
+            if (candidate.url === undefined) {
+                throw new ChannelError("a2a-direct", "no_channel_candidate", "a2a-direct candidate is missing url");
+            }
+            const channel = new A2ADirectChannel({
+                url: candidate.url,
+                ledger: deps.ledger,
+                idempotency: deps.idempotency,
+                now: deps.now,
+                fetchImpl: deps.fetchImpl,
+                timeoutMs: deps.timeoutMs ?? input.timeoutMs,
+            });
+            return channel.open(input);
+        }
+        case "shopping-cli-hosted": {
+            const client = deps.commerce?.(candidate.config_id) ?? null;
+            if (client === null) {
+                throw new ChannelError("shopping-cli-hosted", "commerce_client_not_configured", "shopping-cli-hosted candidate selected but no commerce client is configured (config_id=" +
+                    `${candidate.config_id ?? "default"})`);
+            }
+            const channel = new ShoppingCliHostedChannel({
+                client,
+                ledger: deps.ledger,
+                now: deps.now,
+            });
+            return channel.open(input);
+        }
+        case "platform-api": {
+            const channel = new PlatformApiChannel({
+                configured: deps.platform?.configured ?? false,
+                credentialRef: deps.platform?.credentialRef ?? candidate.credential_ref,
+            });
+            return channel.open(input);
+        }
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/counterparty/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/counterparty/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,OAAO,EACL,YAAY,EACZ,sBAAsB,GAIvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAe7D;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAA4B,EAC5B,IAAwB,EACxB,KAAuB;IAEvB,MAAM,SAAS,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,YAAY,CACpB,cAAc,EACd,sBAAsB,EACtB,gDAAgD,OAAO,CAAC,QAAQ,EAAE,CACnE,CAAC;IACJ,CAAC;IAED,QAAQ,SAAS,CAAC,IAAI,EAAE,CAAC;QACvB,KAAK,YAAY,CAAC,CAAC,CAAC;YAClB,IAAI,SAAS,CAAC,GAAG,KAAK,SAAS,EAAE,CAAC;gBAChC,MAAM,IAAI,YAAY,CAAC,YAAY,EAAE,sBAAsB,EAAE,qCAAqC,CAAC,CAAC;YACtG,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,gBAAgB,CAAC;gBACnC,GAAG,EAAE,SAAS,CAAC,GAAG;gBAClB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS;aAC7C,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,qBAAqB,CAAC,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC;YAC5D,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;gBACpB,MAAM,IAAI,YAAY,CACpB,qBAAqB,EACrB,gCAAgC,EAChC,yFAAyF;oBACvF,GAAG,SAAS,CAAC,SAAS,IAAI,SAAS,GAAG,CACzC,CAAC;YACJ,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,wBAAwB,CAAC;gBAC3C,MAAM;gBACN,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,EAAE,IAAI,CAAC,GAAG;aACd,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;QACD,KAAK,cAAc,CAAC,CAAC,CAAC;YACpB,MAAM,OAAO,GAAG,IAAI,kBAAkB,CAAC;gBACrC,UAAU,EAAE,IAAI,CAAC,QAAQ,EAAE,UAAU,IAAI,KAAK;gBAC9C,aAAa,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,IAAI,SAAS,CAAC,cAAc;aACxE,CAAC,CAAC;YACH,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/counterparty/shopping-cli-hosted/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { CommerceClient } from "../../commerce/types.js";
+import type { LedgerStore } from "../../negotiation/ledger/index.js";
+import { type ChannelHandle, type ChannelOpenInput, type CounterpartyChannel } from "../channel.js";
+export interface ShoppingCliHostedChannelOptions {
+    /** shopping-cli 客户端（HttpCommerceClient / FakeCommerceClient）。 */
+    client: CommerceClient;
+    ledger?: LedgerStore;
+    now?: () => string;
+    /** 本方 agent 标识（幂等键前缀）；缺省 "kiwi.hosted"。 */
+    agentId?: string;
+}
+export declare class ShoppingCliHostedChannel implements CounterpartyChannel {
+    readonly kind: "shopping-cli-hosted";
+    private readonly client;
+    private readonly ledger?;
+    private readonly now;
+    private readonly agentId;
+    private readonly adapter;
+    constructor(options: ShoppingCliHostedChannelOptions);
+    open(input: ChannelOpenInput): Promise<ChannelHandle>;
+}