@harrylabsj/kiwi 0.6.0

package/dist/a2a/server/errors.js

@@ -0,0 +1,178 @@
+/**
+ * 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.
+ */
+/**
+ * JSON-RPC 错误映射（A2A JSONRPC binding + KNP §18 协议错误）。
+ *
+ * 分层（子规范 §24 A2A Binding）：
+ * - transport 层：HTTP 状态码表达帧级/传输级失败（400 解析失败 / 401-403 认证 /
+ *   413 body 超限 / 404 未知路径 / 405 方法不允许）。
+ * - JSON-RPC 层：合法帧内的失败用 JSON-RPC error object 表达；KNP 协议错误
+ *   用固定 code=-32050 携带 `data.protocol_code`（词表见
+ *   negotiation/domain/common.ts PROTOCOL_ERROR_CODES）。
+ *
+ * fail-closed（基线 §4.6 / §36）：任何无法证明合法即拒绝；内部异常细节一律
+ * 不落回远端响应（§4.5 Remote Content Is Untrusted / 不变量 11）。
+ *
+ * 错误码映射表（本模块为单一事实来源）：
+ *
+ * | 条件                                             | HTTP | JSON-RPC code | data.protocol_code        |
+ * |--------------------------------------------------|------|---------------|---------------------------|
+ * | body 非 JSON / 非 JSON-RPC 对象                   | 400  | -32700        | —                         |
+ * | JSON-RPC 帧非法（非 2.0 / 缺 method / id 非串）    | 400  | -32600        | —                         |
+ * | 未知 method                                      | 200  | -32601        | —                         |
+ * | method 参数形状非法                                | 200  | -32602        | —                         |
+ * | tasks/get 未知 taskId                             | 200  | -32004        | —                         |
+ * | A2A Message / KNP envelope schema 非法            | 200  | -32050        | schema_invalid            |
+ * | KNP 版本不支持                                    | 200  | -32050        | protocol_version_unsupported |
+ * | 幂等同 key 异 digest                              | 200  | -32050        | idempotency_conflict      |
+ * | handler 返回协议错误                               | 200  | -32050        | <handler.protocolCode>    |
+ * | handler / ledger 内部异常（不泄漏细节）            | 200  | -32603        | temporarily_unavailable   |
+ * | 认证缺失（未携带凭据）                             | 401  | -32051        | authentication_required   |
+ * | 认证失败（凭据无效 / 非 loopback 拒绝）            | 403  | -32051        | authorization_failed      |
+ * | body 超过 maxPayloadBytes                         | 413  | -32052        | payload_too_large         |
+ */
+import { NegotiationValidationError } from "../../negotiation/domain/common.js";
+/** JSON-RPC 2.0 标准 code + A2A/KNP 应用 code。 */
+export const JSONRPC_CODES = {
+    PARSE_ERROR: -32700,
+    INVALID_REQUEST: -32600,
+    METHOD_NOT_FOUND: -32601,
+    INVALID_PARAMS: -32602,
+    INTERNAL_ERROR: -32603,
+    /** A2A v1.0: TaskNotFound。 */
+    TASK_NOT_FOUND: -32004,
+    /** KNP 协议错误载体：真实 code 在 data.protocol_code（§18 词表）。 */
+    KNP_PROTOCOL_ERROR: -32050,
+    /** 认证失败载体：protocol_code ∈ {authentication_required, authorization_failed}。 */
+    AUTH_ERROR: -32051,
+    /** body 超限载体：protocol_code = payload_too_large。 */
+    PAYLOAD_TOO_LARGE: -32052,
+};
+/**
+ * 服务器内协议级失败信号。pipeline / http 层内部抛出，由 JSON-RPC 响应层捕获
+ * 并翻译为 error object。message 是给日志/调用方看的通用文案，不含内部细节。
+ */
+export class ServerProtocolError extends Error {
+    body;
+    constructor(body) {
+        super(body.message);
+        this.name = "ServerProtocolError";
+        this.body = body;
+    }
+}
+/** KNP 协议错误（§18 词表）。 */
+export function protocolError(code, detail) {
+    return new ServerProtocolError({
+        code: JSONRPC_CODES.KNP_PROTOCOL_ERROR,
+        message: detail,
+        data: { protocol_code: code, detail },
+    });
+}
+/** 入站内容 schema 非法（§4.6 fail-closed 默认码）。 */
+export function schemaInvalid(detail) {
+    return protocolError("schema_invalid", detail);
+}
+/** 内部异常 → 通用错误，绝不携带原始异常 message（§4.5 / §36-11）。 */
+export function internalServerError() {
+    return new ServerProtocolError({
+        code: JSONRPC_CODES.INTERNAL_ERROR,
+        message: "internal error",
+        data: { protocol_code: "temporarily_unavailable" },
+    });
+}
+/**
+ * 认证失败（HTTP 层使用，帧 id 未知故返回 null）。
+ * protocol_code ∈ {authentication_required, authorization_failed, identity_rejected,
+ * replay_detected}。identity_rejected 与 replay_detected 是 §32 词表里认证相关的
+ * 额外结果：身份绑定冲突（403，永久拒绝）与重放（401，换新签名可重试）。
+ */
+export function authError(protocolCode) {
+    let httpStatus;
+    let message;
+    switch (protocolCode) {
+        case "authentication_required":
+            httpStatus = 401;
+            message = "authentication required";
+            break;
+        case "replay_detected":
+            httpStatus = 401;
+            message = "replay detected";
+            break;
+        case "authorization_failed":
+            httpStatus = 403;
+            message = "authorization failed";
+            break;
+        case "identity_rejected":
+            httpStatus = 403;
+            message = "identity rejected";
+            break;
+    }
+    return {
+        httpStatus,
+        body: {
+            code: JSONRPC_CODES.AUTH_ERROR,
+            message,
+            data: { protocol_code: protocolCode },
+        },
+    };
+}
+/**
+ * 限流拒绝（WP3 §31）：走既有 KNP 协议错误载体（-32050），protocol_code =
+ * rate_limited，data 携带 retry_after（秒）对齐 UCP 429/503 的 backoff 语义。
+ */
+export function rateLimited(retryAfterSeconds, detail) {
+    return new ServerProtocolError({
+        code: JSONRPC_CODES.KNP_PROTOCOL_ERROR,
+        message: detail,
+        data: { protocol_code: "rate_limited", retry_after: retryAfterSeconds, detail },
+    });
+}
+/** 取任意异常的 protocol_code（错误表统一读取口；未知返回 undefined）。 */
+export function protocolCodeOf(err) {
+    if (err instanceof ServerProtocolError) {
+        const data = err.body.data;
+        if (data !== undefined && typeof data.protocol_code === "string") {
+            return data.protocol_code;
+        }
+    }
+    if (err instanceof NegotiationValidationError)
+        return err.code;
+    return undefined;
+}
+/** body 超限（HTTP 层使用）。 */
+export function payloadTooLarge(maxBytes) {
+    return {
+        httpStatus: 413,
+        body: {
+            code: JSONRPC_CODES.PAYLOAD_TOO_LARGE,
+            message: "request body exceeds maximum payload size",
+            data: { protocol_code: "payload_too_large", max_bytes: maxBytes },
+        },
+    };
+}
+/** 把 KNP 校验错误（validateEnvelope 等）翻译为协议错误。 */
+export function fromNegotiationError(err) {
+    return protocolError(err.code, err.message);
+}
+/** 任务不存在（A2A -32004）。 */
+export function taskNotFound(taskId) {
+    return {
+        code: JSONRPC_CODES.TASK_NOT_FOUND,
+        message: `task ${taskId} not found`,
+        data: { taskId },
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/a2a/server/errors.js.map

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

package/dist/a2a/server/handler.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 { NegotiationHandler } from "./types.js";
+/** 原样回显已校验 envelope 的安全桩。 */
+export declare function echoHandler(): NegotiationHandler;
+/** 全部拒绝的安全桩（缺省 handler）。 */
+export declare function declineHandler(reasonCode?: string): NegotiationHandler;
+/** 未配置 handler 时的 fail-closed 默认。 */
+export declare function defaultHandler(): NegotiationHandler;

package/dist/a2a/server/handler.js

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/**
+ * NegotiationHandler 安全桩（接口定义见 types.ts）。
+ *
+ * 本 WP 不接线真正的 Negotiation Engine（后续 WP）。这里提供两个安全默认：
+ *   - echoHandler     校验通过后原样回显 KNP envelope（ack: true），无任何副作用，
+ *                     适合往返测试 / 协议调试。
+ *   - declineHandler  一律拒绝（reason_code 默认 "handler_not_configured"）——
+ *                     fail-closed 默认（§4.6）：未配置引擎时不产生任何商业承诺。
+ *
+ * 两个桩都不触发本地工具、不写 Principal Memory（基线 §4.5 / §36-13）。
+ */
+import { uuidv7 } from "../../negotiation/domain/identifiers.js";
+/** 原样回显已校验 envelope 的安全桩。 */
+export function echoHandler() {
+    return {
+        name: "echo",
+        async handle(ctx) {
+            return {
+                kind: "accepted",
+                message: {
+                    role: "agent",
+                    parts: [{ kind: "data", data: { knp_envelope: ctx.envelope, ack: true } }],
+                    messageId: `msg_${uuidv7()}`,
+                },
+            };
+        },
+    };
+}
+/** 全部拒绝的安全桩（缺省 handler）。 */
+export function declineHandler(reasonCode = "handler_not_configured") {
+    return {
+        name: "decline",
+        async handle(_ctx) {
+            return { kind: "declined", reasonCode };
+        },
+    };
+}
+/** 未配置 handler 时的 fail-closed 默认。 */
+export function defaultHandler() {
+    return declineHandler();
+}
+//# sourceMappingURL=handler.js.map

package/dist/a2a/server/handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.js","sourceRoot":"","sources":["../../../src/a2a/server/handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AAOjE,6BAA6B;AAC7B,MAAM,UAAU,WAAW;IACzB,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,KAAK,CAAC,MAAM,CAAC,GAA8B;YACzC,OAAO;gBACL,IAAI,EAAE,UAAU;gBAChB,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC;oBAC1E,SAAS,EAAE,OAAO,MAAM,EAAE,EAAE;iBAC7B;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4BAA4B;AAC5B,MAAM,UAAU,cAAc,CAAC,UAAU,GAAG,wBAAwB;IAClE,OAAO;QACL,IAAI,EAAE,SAAS;QACf,KAAK,CAAC,MAAM,CAAC,IAA+B;YAC1C,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qCAAqC;AACrC,MAAM,UAAU,cAAc;IAC5B,OAAO,cAAc,EAAE,CAAC;AAC1B,CAAC"}

package/dist/a2a/server/inbound-message.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 入站 A2A Message 严格解析 + KNP envelope 提取（子规范 §24.3）。
+ *
+ * 所有入站内容视为 untrusted（基线 §4.5 / §36-12）：对象形状、字段类型、Part
+ * kind、Data Part 结构全部 fail-closed。解析失败抛 schema_invalid
+ * （ServerProtocolError，errors.ts），绝不静默容错。
+ *
+ * KNP 约定（§24.3）：结构化 Data Part 的 `knp_envelope` 键携带 Negotiation
+ * Envelope；文本 Part 可省略。存在多个 Data Part 时取第一个含 `knp_envelope`
+ * 的 Part；同值重复允许，冲突（多个不同 envelope）fail-closed。
+ */
+import type { A2AMessage } from "../client/index.js";
+/** Data Part 中携带 KNP envelope 的键名（§24.3 约定）。 */
+export declare const KNP_ENVELOPE_DATA_KEY = "knp_envelope";
+/** 严格解析入站 A2A Message（untrusted）。失败抛 schema_invalid。 */
+export declare function parseInboundMessage(value: unknown): A2AMessage;
+/**
+ * 从 A2A Message 的 Data Part 提取 KNP envelope（raw，未校验）。
+ * 无 Data Part 携带 `knp_envelope` 或值非对象 → schema_invalid（§24.3）。
+ * 多个不同 envelope → schema_invalid（冲突 fail-closed）。
+ */
+export declare function extractKnpEnvelope(message: A2AMessage): Record<string, unknown>;

package/dist/a2a/server/inbound-message.js

@@ -0,0 +1,104 @@
+/**
+ * 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 { schemaInvalid } from "./errors.js";
+/** Data Part 中携带 KNP envelope 的键名（§24.3 约定）。 */
+export const KNP_ENVELOPE_DATA_KEY = "knp_envelope";
+function requireObject(value, path) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw schemaInvalid(`${path} must be an object`);
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw schemaInvalid(`${path} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalRecord(value, path) {
+    return value === undefined ? undefined : requireObject(value, path);
+}
+function parsePart(value, path) {
+    const obj = requireObject(value, path);
+    const kind = requireNonEmptyString(obj.kind, `${path}/kind`);
+    if (kind === "text") {
+        if (typeof obj.text !== "string")
+            throw schemaInvalid(`${path}/text must be a string`);
+        return { kind: "text", text: obj.text };
+    }
+    if (kind === "data") {
+        return { kind: "data", data: requireObject(obj.data, `${path}/data`) };
+    }
+    throw schemaInvalid(`${path}/kind is unsupported: ${kind}`);
+}
+/** 严格解析入站 A2A Message（untrusted）。失败抛 schema_invalid。 */
+export function parseInboundMessage(value) {
+    const obj = requireObject(value, "params/message");
+    const role = obj.role;
+    if (role !== "agent" && role !== "user") {
+        throw schemaInvalid("params/message/role must be agent or user");
+    }
+    if (!Array.isArray(obj.parts) || obj.parts.length === 0) {
+        throw schemaInvalid("params/message/parts must be a non-empty array");
+    }
+    const message = {
+        role,
+        parts: obj.parts.map((part, index) => parsePart(part, `params/message/parts/${index}`)),
+        messageId: requireNonEmptyString(obj.messageId, "params/message/messageId"),
+    };
+    if (obj.taskId !== undefined) {
+        message.taskId = requireNonEmptyString(obj.taskId, "params/message/taskId");
+    }
+    if (obj.contextId !== undefined) {
+        message.contextId = requireNonEmptyString(obj.contextId, "params/message/contextId");
+    }
+    const metadata = optionalRecord(obj.metadata, "params/message/metadata");
+    if (metadata !== undefined)
+        message.metadata = metadata;
+    return message;
+}
+/**
+ * 从 A2A Message 的 Data Part 提取 KNP envelope（raw，未校验）。
+ * 无 Data Part 携带 `knp_envelope` 或值非对象 → schema_invalid（§24.3）。
+ * 多个不同 envelope → schema_invalid（冲突 fail-closed）。
+ */
+export function extractKnpEnvelope(message) {
+    const envelopes = [];
+    for (const part of message.parts) {
+        if (part.kind !== "data")
+            continue;
+        const data = part.data;
+        if (!(KNP_ENVELOPE_DATA_KEY in data))
+            continue;
+        const value = data[KNP_ENVELOPE_DATA_KEY];
+        const envelope = requireObject(value, `data.${KNP_ENVELOPE_DATA_KEY}`);
+        envelopes.push(envelope);
+    }
+    if (envelopes.length === 0) {
+        throw schemaInvalid(`message has no data part carrying "${KNP_ENVELOPE_DATA_KEY}" (KNP envelope, §24.3)`);
+    }
+    const first = envelopes[0];
+    if (first === undefined) {
+        throw schemaInvalid("KNP envelope data part is empty");
+    }
+    for (const other of envelopes.slice(1)) {
+        if (JSON.stringify(other) !== JSON.stringify(first)) {
+            throw schemaInvalid("multiple conflicting KNP envelopes in message data parts");
+        }
+    }
+    return first;
+}
+//# sourceMappingURL=inbound-message.js.map

package/dist/a2a/server/inbound-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inbound-message.js","sourceRoot":"","sources":["../../../src/a2a/server/inbound-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAeH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,gDAAgD;AAChD,MAAM,CAAC,MAAM,qBAAqB,GAAG,cAAc,CAAC;AAEpD,SAAS,aAAa,CAAC,KAAc,EAAE,IAAY;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,MAAM,aAAa,CAAC,GAAG,IAAI,oBAAoB,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,KAAgC,CAAC;AAC1C,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAc,EAAE,IAAY;IACzD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,aAAa,CAAC,GAAG,IAAI,6BAA6B,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,KAAc,EAAE,IAAY;IAClD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;AACtE,CAAC;AAED,SAAS,SAAS,CAAC,KAAc,EAAE,IAAY;IAC7C,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,qBAAqB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;YAAE,MAAM,aAAa,CAAC,GAAG,IAAI,wBAAwB,CAAC,CAAC;QACvF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC;IACzE,CAAC;IACD,MAAM,aAAa,CAAC,GAAG,IAAI,yBAAyB,IAAI,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,MAAM,GAAG,GAAG,aAAa,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACxC,MAAM,aAAa,CAAC,2CAA2C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,aAAa,CAAC,gDAAgD,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,OAAO,GAAe;QAC1B,IAAI;QACJ,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,wBAAwB,KAAK,EAAE,CAAC,CAAC;QACvF,SAAS,EAAE,qBAAqB,CAAC,GAAG,CAAC,SAAS,EAAE,0BAA0B,CAAC;KAC5E,CAAC;IACF,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,CAAC,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,SAAS,GAAG,qBAAqB,CAAC,GAAG,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC;IACvF,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,QAAQ,EAAE,yBAAyB,CAAC,CAAC;IACzE,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;IACxD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAmB;IACpD,MAAM,SAAS,GAA8B,EAAE,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,SAAS;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,CAAC,qBAAqB,IAAI,IAAI,CAAC;YAAE,SAAS;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,EAAE,QAAQ,qBAAqB,EAAE,CAAC,CAAC;QACvE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,aAAa,CACjB,sCAAsC,qBAAqB,yBAAyB,CACrF,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,aAAa,CAAC,iCAAiC,CAAC,CAAC;IACzD,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,IAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACpD,MAAM,aAAa,CAAC,0DAA0D,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/a2a/server/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * a2a/server — A2A JSONRPC binding 入站 server（WP2，node:http，零新增依赖）。
+ *
+ * 端点面：
+ *   GET  /.well-known/agent-card.json    Agent Card（含 KNP negotiation extension 声明）；
+ *   POST <a2aPath>                        JSON-RPC：message/send、tasks/get。
+ *
+ * 安全：所有入站内容 untrusted（基线 §4.5 / §36）；schema 不过 → schema_invalid；
+ * 未知版本 → protocol_version_unsupported；幂等同 key 异 digest → idempotency_conflict；
+ * body 大小上限；body 解析失败 fail-closed；未配置 AuthVerifier 时默认只接受
+ * loopback 请求（fail-closed）。
+ */
+export { A2AServer } from "./server.js";
+export { buildAgentCard } from "./card.js";
+export { buildUcpProfile, WELL_KNOWN_UCP_PATH } from "./ucp.js";
+export type { BuiltUcpProfile, UcpPublishOptions, UcpVendorOptions } from "./ucp.js";
+export { A2AServerThrottle, DEFAULT_THROTTLE_TIERS, DEFAULT_UNVERIFIED_SCALE, DEFAULT_WINDOW_MS, domainFromUcpProfile, } from "./throttle.js";
+export type { TaskSlotResult, ThrottleDecision, ThrottleOptions, ThrottleRequest, ThrottleTierTable, TrustTierLimits, } from "./throttle.js";
+export { parseUcpAgentHeader, serializeRfc8941String, serializeUcpAgentHeader, UCP_AGENT_HEADER, UCP_AGENT_PROFILE_MEMBER, } from "../ucp-agent.js";
+export { defaultAuthVerifier, LoopbackOnlyAuthVerifier, NoneAuthVerifier, StaticBearerAuthVerifier, } from "./auth.js";
+export { HttpMessageSignatureVerifier } from "../../trust/identity/index.js";
+export { declineHandler, defaultHandler, echoHandler } from "./handler.js";
+export { InboundPipeline } from "./pipeline.js";
+export { TaskRegistry, isKnownTaskState, newArtifactId, newTaskId } from "./task-registry.js";
+export { JSONRPC_CODES, ServerProtocolError, authError, fromNegotiationError, internalServerError, payloadTooLarge, protocolCodeOf, protocolError, rateLimited, schemaInvalid, taskNotFound, } from "./errors.js";
+export type { JsonRpcErrorBody } from "./errors.js";
+export { extractKnpEnvelope, KNP_ENVELOPE_DATA_KEY, parseInboundMessage, } from "./inbound-message.js";
+export type { A2AServerOptions, AgentCardConfig, AgentCardConfigProvider, AuthContext, AuthResult, AuthVerifier, InboundNegotiationContext, NegotiationHandler, NegotiationHandlerResult, } from "./types.js";

package/dist/a2a/server/index.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * a2a/server — A2A JSONRPC binding 入站 server（WP2，node:http，零新增依赖）。
+ *
+ * 端点面：
+ *   GET  /.well-known/agent-card.json    Agent Card（含 KNP negotiation extension 声明）；
+ *   POST <a2aPath>                        JSON-RPC：message/send、tasks/get。
+ *
+ * 安全：所有入站内容 untrusted（基线 §4.5 / §36）；schema 不过 → schema_invalid；
+ * 未知版本 → protocol_version_unsupported；幂等同 key 异 digest → idempotency_conflict；
+ * body 大小上限；body 解析失败 fail-closed；未配置 AuthVerifier 时默认只接受
+ * loopback 请求（fail-closed）。
+ */
+export { A2AServer } from "./server.js";
+export { buildAgentCard } from "./card.js";
+export { buildUcpProfile, WELL_KNOWN_UCP_PATH } from "./ucp.js";
+export { A2AServerThrottle, DEFAULT_THROTTLE_TIERS, DEFAULT_UNVERIFIED_SCALE, DEFAULT_WINDOW_MS, domainFromUcpProfile, } from "./throttle.js";
+export { parseUcpAgentHeader, serializeRfc8941String, serializeUcpAgentHeader, UCP_AGENT_HEADER, UCP_AGENT_PROFILE_MEMBER, } from "../ucp-agent.js";
+export { defaultAuthVerifier, LoopbackOnlyAuthVerifier, NoneAuthVerifier, StaticBearerAuthVerifier, } from "./auth.js";
+// WP5 完整身份方案（RFC 9421 HTTP Message Signature + Agent Card JWS +
+// TrustPolicy + 身份绑定）。实现位于 src/trust/identity。
+export { HttpMessageSignatureVerifier } from "../../trust/identity/index.js";
+export { declineHandler, defaultHandler, echoHandler } from "./handler.js";
+export { InboundPipeline } from "./pipeline.js";
+export { TaskRegistry, isKnownTaskState, newArtifactId, newTaskId } from "./task-registry.js";
+export { JSONRPC_CODES, ServerProtocolError, authError, fromNegotiationError, internalServerError, payloadTooLarge, protocolCodeOf, protocolError, rateLimited, schemaInvalid, taskNotFound, } from "./errors.js";
+export { extractKnpEnvelope, KNP_ENVELOPE_DATA_KEY, parseInboundMessage, } from "./inbound-message.js";
+//# sourceMappingURL=index.js.map

package/dist/a2a/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/a2a/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEhE,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,iBAAiB,EACjB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AASvB,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,WAAW,CAAC;AACnB,gEAAgE;AAChE,+CAA+C;AAC/C,OAAO,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC9F,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,oBAAoB,EACpB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC"}

package/dist/a2a/server/merchant-handler.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * 生产 merchant A2A handler（`kiwi agent serve` 用）——脚本化 KNP 磋商：
+ *
+ *   rfq/inquiry → offer；offer → counter_offer（还价到 DEAL 价）；
+ *   counter_offer → conditional_offer；clarification → 文字澄清应答；
+ *   accept_nonbinding → agreement artifact（三副作用 flag 恒 false）；
+ *   withdraw/decline/cancel → 文字确认。
+ *
+ * 每个出站回复落 merchant 侧 Ledger（append-only，§22）。这是 `kiwi agent serve`
+ * 的确定性 merchant 行为；未来可替换为 LLM 驱动的 Negotiation Engine（同一 handler 接缝）。
+ */
+import type { CommerceDataSource } from "../../commerce/data-source.js";
+import { LedgerStore } from "../../negotiation/ledger/index.js";
+import type { NegotiationHandler } from "./types.js";
+export declare const MERCHANT_CAPABILITY = "com.harrylabsj.kiwi.shopping.negotiation";
+export declare const MERCHANT_SKU = "SKU-001";
+export declare const MERCHANT_CURRENCY = "CNY";
+export declare const MERCHANT_OFFER_PRICE_MINOR = 85000;
+export declare const MERCHANT_DEAL_PRICE_MINOR = 83500;
+export declare const MERCHANT_QUANTITY = 200;
+export declare const MERCHANT_DELIVERY_BEFORE = "2026-08-20T18:00:00Z";
+export interface MerchantHandlerOptions {
+    ledger: LedgerStore;
+    now: () => string;
+    sender: string;
+    counterparty: string;
+    /** rfq→offer 的初始报价（amount_minor）；缺省 85000。 */
+    offerPriceMinor?: number;
+    /** 真实商品源（接 shopping-cli /products/{sku} 等开放商品层）；缺省用内置演示价。 */
+    productSource?: MerchantProductSource;
+    /** 条件成交折扣百分比（deal = base × (1 - pct/100)）；缺省 5。 */
+    dealDiscountPercent?: number;
+}
+/**
+ * 真实商品源：给定 SKU 返回价目（shopping-cli 开放层/ERP/商品表均可接入）。
+ * `price` 单位为**元**（major units，与 resolveProduct 的 `*100 → amount_minor`
+ * 约定一致，也符合 shopping-cli wire 值；测试桩 `{price: 99}` → 9900 minor 同此）。
+ */
+export interface MerchantProductSource {
+    getProduct(sku: string): Promise<{
+        price: number;
+        currency: string;
+        title?: string;
+        stock?: number;
+    }>;
+}
+/**
+ * 把 CommerceDataSource（v0.7.0 数据侧边界）适配成 MerchantProductSource。
+ * price_minor（分）→ 元（major）转换在此完成，与接口"元"单位约定一致；
+ * 未知 SKU → 抛错（resolveProduct 回退演示价，缺省行为不变）。
+ */
+export declare function dataSourceProductSource(dataSource: CommerceDataSource): MerchantProductSource;
+/** 构造生产 merchant KNP handler。 */
+export declare function createMerchantHandler(options: MerchantHandlerOptions): NegotiationHandler;