@harrylabsj/kiwi 0.6.0

package/dist/a2a/node.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.
+ */
+import type { AgentProfile } from "../config/profile.js";
+export interface A2aNodeOptions {
+    profile: AgentProfile;
+    /** agent catalog base URL（merchant 自动注册用）。 */
+    catalog?: string;
+    /** 首选端口（缺省按角色：merchant 9000 / buyer 9001）。占用则自动换。 */
+    preferredPort?: number;
+    /** KIWI_CATALOG_OWNER_TOKEN_SECRET（merchant 注册绑定 owner 语义）。 */
+    ownerTokenSecret?: string;
+}
+export interface A2aNodeHandle {
+    role: "buyer" | "merchant";
+    /** 节点 base URL。 */
+    url: string;
+    /** Agent Card well-known URL。 */
+    agentCardUrl: string;
+    /** 注册进 catalog 的 catalog_agent_id（merchant 角色且有 catalog 时）。 */
+    catalogAgentId?: string;
+    stop(): Promise<void>;
+}
+/** 启动一个 A2A 节点（按 profile 角色）。 */
+export declare function startA2aNode(options: A2aNodeOptions): Promise<A2aNodeHandle>;

package/dist/a2a/node.js

@@ -0,0 +1,155 @@
+/**
+ * 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 节点生命周期（裸 `kiwi` 自动启动用）：
+ *
+ * 一个进程既是对话 agent（chat kernel）又是 A2A 节点（可被发现/磋商）。
+ *   - merchant 角色：A2AServer + 生产 KNP merchant handler，启动时自动注册进
+ *     kiwi-catalog（buyer 据此发现）；
+ *   - buyer 角色：A2AServer + 默认 handler（可被发现，不注册——本流程由 buyer 发起）。
+ *
+ * 端口按角色：merchant→9000、buyer→9001（KIWI_A2A_PORT 覆盖）；占用则
+ * pickFreePort 自动换。
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { A2AServer } from "./server/index.js";
+import { defaultHandler } from "./server/handler.js";
+import { createMerchantHandler } from "./server/merchant-handler.js";
+import { LedgerStore } from "../negotiation/ledger/index.js";
+import { IdempotencyStore } from "../negotiation/idempotency/index.js";
+import { pickFreePort } from "../supervisor/stack-config.js";
+import { registerCatalogAgent } from "../discovery/catalog-source/register.js";
+import { HttpMerchantClient } from "../agent/merchant/merchant-client.js";
+import { ProfileCredentialBroker } from "../agent/merchant/credential-broker.js";
+/** 单调递增时钟：同内容事件在同一毫秒会触发 ledger 内容去重。 */
+function monotonicNow() {
+    let tick = 0;
+    const base = Date.parse("2026-08-07T00:00:00.000Z");
+    return () => {
+        const t = new Date(base + tick);
+        tick += 1;
+        return t.toISOString();
+    };
+}
+/** 优先监听 preferredPort；被占用则换空闲端口。 */
+async function listenPort(preferred) {
+    // 尝试 preferred：失败（EADDRINUSE）则 pickFreePort。
+    const { createServer } = await import("node:net");
+    const tryListen = (port) => new Promise((resolve) => {
+        const s = createServer();
+        s.once("error", () => resolve(false));
+        s.listen(port, "127.0.0.1", () => {
+            s.close();
+            resolve(true);
+        });
+    });
+    // preferred <= 0（含显式 0 / NaN）不尝试：tryListen(0) 会返回"成功"并把
+    // port=0 带进 url（http://127.0.0.1:0），随后 server.listen(0) 换随机端口
+    // 但 holder.baseUrl 仍是无效端口 0——节点 URL 全部指向空。直接 pickFreePort。
+    const port = preferred > 0 && (await tryListen(preferred)) ? preferred : await pickFreePort();
+    return { port, url: `http://127.0.0.1:${port}` };
+}
+/**
+ * 构建真实商品源：读 shopping-cli（开放商品层）的价目。URL 来自
+ * `KIWI_COMMERCE_URL` 覆盖或 profile.commerce.base_url；/products/{sku} 是
+ * 公开只读端点（无需 token），shopping-cli 自身可接 ERP/本地商品表。
+ */
+function buildProductSource(profile) {
+    const commerceUrl = process.env.KIWI_COMMERCE_URL ?? profile.commerce.base_url;
+    const client = new HttpMerchantClient(commerceUrl, new ProfileCredentialBroker(profile));
+    return {
+        getProduct: async (sku) => {
+            const product = await client.getProduct(sku);
+            return { price: product.price, currency: product.currency };
+        },
+    };
+}
+/** 启动一个 A2A 节点（按 profile 角色）。 */
+export async function startA2aNode(options) {
+    const { profile } = options;
+    const role = profile.role;
+    const preferred = options.preferredPort ?? (Number(process.env.KIWI_A2A_PORT ?? "") || (role === "merchant" ? 9000 : 9001));
+    const { port, url } = await listenPort(preferred);
+    const dir = mkdtempSync(path.join(tmpdir(), "kiwi-a2a-node-"));
+    const now = monotonicNow();
+    const ledger = new LedgerStore({ dir, now });
+    const idempotency = new IdempotencyStore({ dir, now });
+    const handler = role === "merchant"
+        ? createMerchantHandler({
+            ledger,
+            now,
+            sender: profile.agent_id,
+            counterparty: "buyer:*",
+            productSource: buildProductSource(profile),
+        })
+        : defaultHandler();
+    const holder = { baseUrl: url };
+    const server = new A2AServer({
+        // A2AServerOptions.card 是 AgentCardConfigProvider：返回 config，server 内部再 buildAgentCard。
+        // name 用干净显示名，不掺 agent_id（形如 agent:token，会被 card secret 扫描器判为 card_has_secret）。
+        card: () => ({
+            name: role === "merchant" ? "Kiwi A2A Merchant" : "Kiwi A2A Buyer",
+            description: "Kiwi A2A node",
+            providerOrganization: "Kiwi",
+            version: "1.0.0",
+            baseUrl: holder.baseUrl,
+            a2aPath: "/",
+        }),
+        ledger,
+        idempotency,
+        handler,
+        now,
+    });
+    const httpServer = server.createServer();
+    await new Promise((resolve) => httpServer.listen(port, "127.0.0.1", () => resolve()));
+    holder.baseUrl = url;
+    const agentCardUrl = `${url}/.well-known/agent-card.json`;
+    // merchant 角色：自动注册进 catalog（buyer 据此发现）。
+    let catalogAgentId;
+    if (role === "merchant" && options.catalog !== undefined) {
+        const safeAgentId = profile.agent_id.replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+        const domain = process.env.KIWI_CATALOG_DOMAIN ?? `merchant-${safeAgentId}.local`;
+        try {
+            const reg = await registerCatalogAgent({
+                catalogBaseUrl: options.catalog,
+                domain,
+                agentCardUrl,
+                ucpProfileUrl: `${url}/.well-known/ucp`,
+                merchantId: profile.agent_id,
+                ownerTokenSecret: options.ownerTokenSecret,
+            });
+            catalogAgentId = reg.catalogAgentId;
+        }
+        catch {
+            // 注册失败不阻断节点：buyer 侧仍可经 direct URL 磋商。
+            catalogAgentId = undefined;
+        }
+    }
+    return {
+        role,
+        url,
+        agentCardUrl,
+        catalogAgentId,
+        async stop() {
+            httpServer.closeAllConnections?.();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+            rmSync(dir, { recursive: true, force: true });
+        },
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/a2a/node.js.map

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

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

@@ -0,0 +1,38 @@
+/**
+ * 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 { AuthContext, AuthResult, AuthVerifier } from "./types.js";
+/** 总是放行。identity 固定为 "anonymous"。 */
+export declare class NoneAuthVerifier implements AuthVerifier {
+    readonly name = "none";
+    verify(_ctx: AuthContext): AuthResult;
+}
+/** 静态 Bearer token 校验。 */
+export declare class StaticBearerAuthVerifier implements AuthVerifier {
+    readonly name = "static-bearer";
+    private readonly token;
+    private readonly identity;
+    constructor(token: string, options?: {
+        identity?: string;
+    });
+    verify(ctx: AuthContext): AuthResult;
+}
+/** 只放行 loopback 对端（127.0.0.1 / ::1 / ::ffff:127.0.0.1）。 */
+export declare class LoopbackOnlyAuthVerifier implements AuthVerifier {
+    readonly name = "loopback-only";
+    verify(ctx: AuthContext): AuthResult;
+}
+/** 未配置 verifier 时的 fail-closed 默认。 */
+export declare function defaultAuthVerifier(): AuthVerifier;

package/dist/a2a/server/auth.js

@@ -0,0 +1,112 @@
+/**
+ * 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.
+ */
+/**
+ * AuthVerifier 参考实现（接缝定义见 types.ts）。
+ *
+ * 三个参考实现：
+ *   - NoneAuthVerifier           总是放行（显式可信网络 / 测试用；生产不推荐）。
+ *   - StaticBearerAuthVerifier   校验 `Authorization: Bearer <token>`（静态 token；
+ *                                WP5 会替换为完整身份方案）。
+ *   - LoopbackOnlyAuthVerifier   只放行 loopback 对端 —— 未配置 verifier 时的
+ *                                fail-closed 默认（§4.6）：一个本地-only Kiwi 的
+ *                                A2A Server 不接受远端连接，直到显式配置认证。
+ *
+ * identity 语义：认证通过时返回调用方身份，pipeline 用它作为幂等主键
+ * (sender_identity, message_id) 的 sender 侧（子规范 §20.1）。WP5 完整身份
+ * 方案接入前，loopback 默认以 socket 地址为 identity，静态 bearer 以配置的
+ * identity 为 identity（同一 token 的客户端共享一个幂等身份，message_id 不
+ * 冲突即不会误判 —— 幂等冲突仅在同 message_id 异 digest 时触发）。
+ */
+import { isLoopbackHost } from "../client/url-policy.js";
+/** IPv4-mapped IPv6（::ffff:127.0.0.1）剥前缀后按内嵌 IPv4 判定 loopback。 */
+function isLoopbackAddress(addr) {
+    const lower = addr.toLowerCase();
+    const embedded = lower.startsWith("::ffff:") ? lower.slice("::ffff:".length) : lower;
+    return isLoopbackHost(embedded);
+}
+/** 总是放行。identity 固定为 "anonymous"。 */
+export class NoneAuthVerifier {
+    name = "none";
+    verify(_ctx) {
+        return { authenticated: true, identity: "anonymous" };
+    }
+}
+/** 静态 Bearer token 校验。 */
+export class StaticBearerAuthVerifier {
+    name = "static-bearer";
+    token;
+    identity;
+    constructor(token, options = {}) {
+        if (token.length === 0)
+            throw new Error("StaticBearerAuthVerifier requires a non-empty token");
+        this.token = token;
+        this.identity = options.identity ?? "bearer";
+    }
+    verify(ctx) {
+        const header = ctx.authorizationHeader;
+        if (header === undefined || header === "") {
+            return {
+                authenticated: false,
+                protocolCode: "authentication_required",
+                reason: "missing Authorization header",
+            };
+        }
+        const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+        if (match === null) {
+            return {
+                authenticated: false,
+                protocolCode: "authorization_failed",
+                reason: "Authorization header is not a bearer token",
+            };
+        }
+        const presented = match[1];
+        if (presented !== this.token) {
+            return {
+                authenticated: false,
+                protocolCode: "authorization_failed",
+                reason: "invalid bearer token",
+            };
+        }
+        return { authenticated: true, identity: this.identity };
+    }
+}
+/** 只放行 loopback 对端（127.0.0.1 / ::1 / ::ffff:127.0.0.1）。 */
+export class LoopbackOnlyAuthVerifier {
+    name = "loopback-only";
+    verify(ctx) {
+        const addr = ctx.remoteAddress;
+        if (addr === undefined) {
+            return {
+                authenticated: false,
+                protocolCode: "authorization_failed",
+                reason: "no remote address",
+            };
+        }
+        if (isLoopbackAddress(addr)) {
+            return { authenticated: true, identity: `loopback:${addr}` };
+        }
+        return {
+            authenticated: false,
+            protocolCode: "authorization_failed",
+            reason: "non-loopback peer rejected (fail-closed default)",
+        };
+    }
+}
+/** 未配置 verifier 时的 fail-closed 默认。 */
+export function defaultAuthVerifier() {
+    return new LoopbackOnlyAuthVerifier();
+}
+//# sourceMappingURL=auth.js.map

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * 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 { AgentCard } from "../../discovery/agent-card/index.js";
+import type { AgentCardConfig } from "./types.js";
+/** 从本地配置构建 Agent Card（每次调用重新求值，支持动态 baseUrl）。 */
+export declare function buildAgentCard(config: AgentCardConfig): AgentCard;

package/dist/a2a/server/card.js

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ */
+/**
+ * Agent Card 本地构建（基线 §26 / 子规范 §24.1 Discovery）。
+ *
+ * 从本地配置生成 well-known Agent Card，并声明 Kiwi Negotiation A2A extension
+ * （基线 §8.2）。生成结果过 validateAgentCard 结构校验（fail-closed：
+ * supportedInterfaces 非空、URL http(s)、无 userinfo）。不变量 24：card 只含
+ * 元数据，绝不含静态 secret —— 本模块构造的字段全部来自配置，不读 env secret。
+ */
+import { KIWI_NEGOTIATION_EXTENSION_PATH, validateAgentCard, } from "../../discovery/agent-card/index.js";
+function requireHttpUrl(value, field) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`AgentCardConfig: ${field} must be a valid URL (got "${value}")`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`AgentCardConfig: ${field} must use http or https (got ${url.protocol})`);
+    }
+    if (url.username !== "" || url.password !== "") {
+        throw new Error(`AgentCardConfig: ${field} must not embed credentials (userinfo)`);
+    }
+    return url;
+}
+/** 规范化 JSON-RPC endpoint 路径：确保以 "/" 开头（默认 "/"）。 */
+function normalizePath(p) {
+    if (p === undefined || p === "")
+        return "/";
+    return p.startsWith("/") ? p : `/${p}`;
+}
+/** 从本地配置构建 Agent Card（每次调用重新求值，支持动态 baseUrl）。 */
+export function buildAgentCard(config) {
+    const baseUrl = requireHttpUrl(config.baseUrl, "baseUrl");
+    const a2aPath = normalizePath(config.a2aPath);
+    const endpointUrl = new URL(a2aPath, baseUrl).href;
+    const negotiationExtensionUri = config.negotiationExtensionUri ?? `${baseUrl.origin}${KIWI_NEGOTIATION_EXTENSION_PATH}`;
+    const card = {
+        name: config.name,
+        description: config.description,
+        provider: { organization: config.providerOrganization },
+        version: config.version,
+        url: config.baseUrl,
+        supportedInterfaces: [{ url: endpointUrl, protocolBinding: "JSONRPC", protocolVersion: "1.0" }],
+        capabilities: {
+            extendedAgentCard: true,
+            extensions: [{ uri: negotiationExtensionUri, required: false }],
+        },
+    };
+    if (config.providerUrl !== undefined) {
+        requireHttpUrl(config.providerUrl, "providerUrl");
+        card.provider.url = config.providerUrl;
+    }
+    if (config.skills !== undefined && config.skills.length > 0) {
+        card.skills = config.skills;
+    }
+    if (config.securityScheme !== undefined) {
+        card.securitySchemes = {
+            [config.securityScheme.name]: { type: config.securityScheme.type },
+        };
+        card.security = [{ scheme: config.securityScheme.name }];
+    }
+    // 结构校验兜底：构造有误立即暴露，而不是把坏 card 发给远端。
+    return validateAgentCard(card);
+}
+//# sourceMappingURL=card.js.map

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

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

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

@@ -0,0 +1,109 @@
+/**
+ * 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";
+import type { ProtocolErrorCode } from "../../negotiation/domain/common.js";
+/** JSON-RPC 2.0 标准 code + A2A/KNP 应用 code。 */
+export declare const JSONRPC_CODES: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    /** A2A v1.0: TaskNotFound。 */
+    readonly TASK_NOT_FOUND: -32004;
+    /** KNP 协议错误载体：真实 code 在 data.protocol_code（§18 词表）。 */
+    readonly KNP_PROTOCOL_ERROR: -32050;
+    /** 认证失败载体：protocol_code ∈ {authentication_required, authorization_failed}。 */
+    readonly AUTH_ERROR: -32051;
+    /** body 超限载体：protocol_code = payload_too_large。 */
+    readonly PAYLOAD_TOO_LARGE: -32052;
+};
+export interface JsonRpcErrorBody {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/**
+ * 服务器内协议级失败信号。pipeline / http 层内部抛出，由 JSON-RPC 响应层捕获
+ * 并翻译为 error object。message 是给日志/调用方看的通用文案，不含内部细节。
+ */
+export declare class ServerProtocolError extends Error {
+    readonly body: JsonRpcErrorBody;
+    constructor(body: JsonRpcErrorBody);
+}
+/** KNP 协议错误（§18 词表）。 */
+export declare function protocolError(code: ProtocolErrorCode, detail: string): ServerProtocolError;
+/** 入站内容 schema 非法（§4.6 fail-closed 默认码）。 */
+export declare function schemaInvalid(detail: string): ServerProtocolError;
+/** 内部异常 → 通用错误，绝不携带原始异常 message（§4.5 / §36-11）。 */
+export declare function internalServerError(): ServerProtocolError;
+/**
+ * 认证失败（HTTP 层使用，帧 id 未知故返回 null）。
+ * protocol_code ∈ {authentication_required, authorization_failed, identity_rejected,
+ * replay_detected}。identity_rejected 与 replay_detected 是 §32 词表里认证相关的
+ * 额外结果：身份绑定冲突（403，永久拒绝）与重放（401，换新签名可重试）。
+ */
+export declare function authError(protocolCode: "authentication_required" | "authorization_failed" | "identity_rejected" | "replay_detected"): {
+    httpStatus: number;
+    body: JsonRpcErrorBody;
+};
+/**
+ * 限流拒绝（WP3 §31）：走既有 KNP 协议错误载体（-32050），protocol_code =
+ * rate_limited，data 携带 retry_after（秒）对齐 UCP 429/503 的 backoff 语义。
+ */
+export declare function rateLimited(retryAfterSeconds: number, detail: string): ServerProtocolError;
+/** 取任意异常的 protocol_code（错误表统一读取口；未知返回 undefined）。 */
+export declare function protocolCodeOf(err: unknown): ProtocolErrorCode | undefined;
+/** body 超限（HTTP 层使用）。 */
+export declare function payloadTooLarge(maxBytes: number): {
+    httpStatus: number;
+    body: JsonRpcErrorBody;
+};
+/** 把 KNP 校验错误（validateEnvelope 等）翻译为协议错误。 */
+export declare function fromNegotiationError(err: NegotiationValidationError): ServerProtocolError;
+/** 任务不存在（A2A -32004）。 */
+export declare function taskNotFound(taskId: string): JsonRpcErrorBody;