@harrylabsj/kiwi 0.7.4 → 0.7.6

package/dist/a2a/v1/methods.js

@@ -0,0 +1,75 @@
+/**
+ * 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 JSON-RPC 方法名（issue 03）。
+ *
+ * 1.0 方法名与 0.3 legacy 不同：`SendMessage` vs `message/send`、`GetTask` vs
+ * `tasks/get` 等。本文件是方法名 + v1↔legacy 映射的单一来源——声明门禁
+ * （tests/a2a-version-declaration.test.ts）与双栈 client/server 都从这读取。
+ */
+/** A2A 1.0 方法名常量。 */
+export const METHOD_SEND_MESSAGE = "SendMessage";
+export const METHOD_GET_TASK = "GetTask";
+export const METHOD_LIST_TASKS = "ListTasks";
+export const METHOD_CANCEL_TASK = "CancelTask";
+export const METHOD_SUBSCRIBE_TO_TASK = "SubscribeToTask";
+/** A2A 1.0: GetExtendedAgentCard（issue 10 / TCK CARD-EXT-001）。 */
+export const METHOD_GET_EXTENDED_AGENT_CARD = "GetExtendedAgentCard";
+/** A2A 1.0: SendStreamingMessage（issue 10 / TCK JSONRPC-SSE-002：不支持流式 → -32004）。 */
+export const METHOD_SEND_STREAMING_MESSAGE = "SendStreamingMessage";
+/** A2A 1.0 push 通知配置方法（issue 10 / TCK JSONRPC-SSE-002：不支持推送 → -32003）。 */
+export const METHOD_CREATE_PUSH_CONFIG = "CreateTaskPushNotificationConfig";
+export const METHOD_GET_PUSH_CONFIG = "GetTaskPushNotificationConfig";
+export const METHOD_LIST_PUSH_CONFIGS = "ListTaskPushNotificationConfigs";
+export const METHOD_DELETE_PUSH_CONFIG = "DeleteTaskPushNotificationConfig";
+/** A2A 0.3 legacy 方法名常量。 */
+export const LEGACY_METHOD_SEND_MESSAGE = "message/send";
+export const LEGACY_METHOD_GET_TASK = "tasks/get";
+/** 1.0 → legacy 映射（1.0 方法名 → 0.3 方法名）。 */
+export const V1_TO_LEGACY = {
+    [METHOD_SEND_MESSAGE]: LEGACY_METHOD_SEND_MESSAGE,
+    [METHOD_GET_TASK]: LEGACY_METHOD_GET_TASK,
+};
+/** legacy → 1.0 映射（0.3 方法名 → 1.0 方法名）。 */
+export const LEGACY_TO_V1 = Object.fromEntries(Object.entries(V1_TO_LEGACY).map(([v1, legacy]) => [legacy, v1]));
+/** 全部 1.0 方法名集合。 */
+export const V1_METHODS = new Set([
+    METHOD_SEND_MESSAGE,
+    METHOD_GET_TASK,
+    METHOD_LIST_TASKS,
+    METHOD_CANCEL_TASK,
+    METHOD_SUBSCRIBE_TO_TASK,
+    METHOD_GET_EXTENDED_AGENT_CARD,
+    METHOD_SEND_STREAMING_MESSAGE,
+    METHOD_CREATE_PUSH_CONFIG,
+    METHOD_GET_PUSH_CONFIG,
+    METHOD_LIST_PUSH_CONFIGS,
+    METHOD_DELETE_PUSH_CONFIG,
+]);
+/** 全部 0.3 legacy 方法名集合。 */
+export const LEGACY_METHODS = new Set([
+    LEGACY_METHOD_SEND_MESSAGE,
+    LEGACY_METHOD_GET_TASK,
+]);
+/** 给定方法名是否为 1.0 方法。 */
+export function isV1Method(method) {
+    return V1_METHODS.has(method);
+}
+/** 给定方法名是否为 0.3 legacy 方法。 */
+export function isLegacyMethod(method) {
+    return LEGACY_METHODS.has(method);
+}
+//# sourceMappingURL=methods.js.map

package/dist/a2a/v1/methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.js","sourceRoot":"","sources":["../../../src/a2a/v1/methods.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;GAMG;AAEH,qBAAqB;AACrB,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AACjD,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AACzC,MAAM,CAAC,MAAM,iBAAiB,GAAG,WAAW,CAAC;AAC7C,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;AAC1D,kEAAkE;AAClE,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AACrE,oFAAoF;AACpF,MAAM,CAAC,MAAM,6BAA6B,GAAG,sBAAsB,CAAC;AACpE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,yBAAyB,GAAG,kCAAkC,CAAC;AAC5E,MAAM,CAAC,MAAM,sBAAsB,GAAG,+BAA+B,CAAC;AACtE,MAAM,CAAC,MAAM,wBAAwB,GAAG,iCAAiC,CAAC;AAC1E,MAAM,CAAC,MAAM,yBAAyB,GAAG,kCAAkC,CAAC;AAE5E,4BAA4B;AAC5B,MAAM,CAAC,MAAM,0BAA0B,GAAG,cAAc,CAAC;AACzD,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAqC;IAC5D,CAAC,mBAAmB,CAAC,EAAE,0BAA0B;IACjD,CAAC,eAAe,CAAC,EAAE,sBAAsB;CAC1C,CAAC;AAEF,0CAA0C;AAC1C,MAAM,CAAC,MAAM,YAAY,GAAqC,MAAM,CAAC,WAAW,CAC9E,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CACjE,CAAC;AAEF,oBAAoB;AACpB,MAAM,CAAC,MAAM,UAAU,GAAwB,IAAI,GAAG,CAAC;IACrD,mBAAmB;IACnB,eAAe;IACf,iBAAiB;IACjB,kBAAkB;IAClB,wBAAwB;IACxB,8BAA8B;IAC9B,6BAA6B;IAC7B,yBAAyB;IACzB,sBAAsB;IACtB,wBAAwB;IACxB,yBAAyB;CAC1B,CAAC,CAAC;AAEH,2BAA2B;AAC3B,MAAM,CAAC,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IACzD,0BAA0B;IAC1B,sBAAsB;CACvB,CAAC,CAAC;AAEH,uBAAuB;AACvB,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,8BAA8B;AAC9B,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/a2a/v1/part.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 Part 编解码 + KNP DataPart 映射（issue 04，高风险点）。
+ *
+ * 0.3（`{kind:"text"|"data"}`）↔ 1.0（统一 Part，字段存在性判别）双向转换。
+ * KNP 载荷（`knp_envelope` / `agreement`）必须无损往返——磋商内核（envelope
+ * 解析/相位机）100% 复用，只在传输帧层转换。
+ */
+import type { A2APart } from "../client/types.js";
+import type { A2AV1Part, DataPart } from "./types.js";
+/** KNP 载荷承载的 mediaType（KNP envelope 是 JSON）。 */
+export declare const KNP_DATA_MEDIA_TYPE = "application/json";
+/**
+ * 0.3 Part → 1.0 统一 Part。
+ * - text → TextPart；
+ * - data → DataPart（data 原样 + KNP mediaType）。
+ */
+export declare function encodeV1Part(legacy: A2APart): A2AV1Part;
+/**
+ * 1.0 统一 Part → 0.3 Part。
+ * - TextPart → text；
+ * - DataPart → data（原样还原）。
+ * - URLPart/FilePart 在 0.3 模型无等价（0.3 只建模 text/data）→ fail-closed。
+ */
+export declare function decodeV1Part(v1: A2AV1Part): A2APart;
+/** 识别 KNP 载荷 Part（data 内含 knp_envelope 或 agreement）。 */
+export declare function isKnpDataPart(part: A2AV1Part): part is DataPart;
+/**
+ * 输入 Part 是否受支持（issue 10 / TCK CORE-SEND-003）。fail-closed：未知
+ * 形状一律不支持。TextPart 直接支持；DataPart 仅当 mediaType 为
+ * application/json（含 KNP）；带其他 mediaType（如 raw/file/url）不支持 →
+ * server 返回 ContentTypeNotSupportedError（-32005），而非内部错误。
+ */
+export declare function isV1InputPartSupported(part: A2AV1Part): boolean;

package/dist/a2a/v1/part.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+/** KNP 载荷承载的 mediaType（KNP envelope 是 JSON）。 */
+export const KNP_DATA_MEDIA_TYPE = "application/json";
+/**
+ * 0.3 Part → 1.0 统一 Part。
+ * - text → TextPart；
+ * - data → DataPart（data 原样 + KNP mediaType）。
+ */
+export function encodeV1Part(legacy) {
+    if (legacy.kind === "text")
+        return { text: legacy.text };
+    return { data: legacy.data, mediaType: KNP_DATA_MEDIA_TYPE };
+}
+/**
+ * 1.0 统一 Part → 0.3 Part。
+ * - TextPart → text；
+ * - DataPart → data（原样还原）。
+ * - URLPart/FilePart 在 0.3 模型无等价（0.3 只建模 text/data）→ fail-closed。
+ */
+export function decodeV1Part(v1) {
+    if ("text" in v1)
+        return { kind: "text", text: v1.text };
+    if ("data" in v1)
+        return { kind: "data", data: v1.data };
+    throw new Error(`v1 Part 无法映射到 0.3 模型（0.3 只建模 text/data）：${JSON.stringify(v1).slice(0, 200)}`);
+}
+/** 识别 KNP 载荷 Part（data 内含 knp_envelope 或 agreement）。 */
+export function isKnpDataPart(part) {
+    if (!("data" in part))
+        return false;
+    return "knp_envelope" in part.data || "agreement" in part.data;
+}
+/**
+ * 输入 Part 是否受支持（issue 10 / TCK CORE-SEND-003）。fail-closed：未知
+ * 形状一律不支持。TextPart 直接支持；DataPart 仅当 mediaType 为
+ * application/json（含 KNP）；带其他 mediaType（如 raw/file/url）不支持 →
+ * server 返回 ContentTypeNotSupportedError（-32005），而非内部错误。
+ */
+export function isV1InputPartSupported(part) {
+    if (typeof part !== "object" || part === null)
+        return false;
+    if ("text" in part)
+        return true;
+    const mediaType = "mediaType" in part && typeof part.mediaType === "string" ? part.mediaType : undefined;
+    if (mediaType === undefined)
+        return false;
+    return mediaType.startsWith("text/") || mediaType === "application/json";
+}
+//# sourceMappingURL=part.js.map

package/dist/a2a/v1/part.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"part.js","sourceRoot":"","sources":["../../../src/a2a/v1/part.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,gDAAgD;AAChD,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACzD,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,mBAAmB,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,EAAa;IACxC,IAAI,MAAM,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACzD,IAAI,MAAM,IAAI,EAAE;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IACzD,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAC9E,CAAC;AACJ,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,IAAI,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,cAAc,IAAI,IAAI,CAAC,IAAI,IAAI,WAAW,IAAI,IAAI,CAAC,IAAI,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAe;IACpD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC5D,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,SAAS,GACb,WAAW,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IACzF,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,SAAS,KAAK,kBAAkB,CAAC;AAC3E,CAAC"}

package/dist/a2a/v1/types.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 1.0 域模型（issue 02）。
+ *
+ * 与 0.3（`src/a2a/client/types.ts`）的差异：
+ * - **统一 Part**：字段存在性判别（有 `text`=Text / `data`=Data / `url`=URL /
+ *   `raw`=File），**无 `kind` 字段**；`mimeType` → `mediaType`；
+ * - **Role**：`ROLE_AGENT` / `ROLE_USER` 命名常量；
+ * - **TaskState**：大写下划线枚举，含 1.0 新增 `REJECTED` / `AUTH_REQUIRED` /
+ *   `UNSPECIFIED`（0.3 的 `unknown` 在 1.0 语义为 `UNSPECIFIED`）。
+ *
+ * 词表单一来源（仿照 `handoff/destination.ts` 纪律）：本文件是 v1 词表的唯一
+ * 权威，编解码/双栈/TCK 全部从这里导入，不散落字符串。
+ */
+/**
+ * A2A 1.0 Role（wire 值 = proto 枚举名，官方 SDK `@a2a-js/sdk` 如此序列化）。
+ * 输入侧兼容小写 `user`/`agent`（server 归一化，见 normalizeV1Role）。
+ */
+export declare const ROLE_AGENT: "ROLE_AGENT";
+export declare const ROLE_USER: "ROLE_USER";
+export type A2ARole = typeof ROLE_AGENT | typeof ROLE_USER;
+/**
+ * A2A 1.0 TaskState（wire 值 = proto 枚举名 `TASK_STATE_*`，官方 SDK 如此）。
+ * 0.3 `unknown` → 1.0 `TASK_STATE_UNSPECIFIED`。
+ */
+export declare const A2A_TASK_STATES: readonly ["TASK_STATE_SUBMITTED", "TASK_STATE_WORKING", "TASK_STATE_INPUT_REQUIRED", "TASK_STATE_COMPLETED", "TASK_STATE_CANCELED", "TASK_STATE_FAILED", "TASK_STATE_REJECTED", "TASK_STATE_AUTH_REQUIRED", "TASK_STATE_UNSPECIFIED"];
+export type A2ATaskState = (typeof A2A_TASK_STATES)[number];
+/** 0.3 内部小写状态 → 1.0 wire TaskState（server 出站用）。 */
+export declare const LEGACY_TO_V1_STATE: Readonly<Record<string, string>>;
+/** 1.0 wire TaskState → 0.3 内部小写状态（client 入站用）。 */
+export declare const V1_STATE_TO_LEGACY: Readonly<Record<string, string>>;
+/** A2A 1.0 统一 Part：字段存在性判别（无 `kind`）。 */
+export type A2AV1Part = TextPart | DataPart | FilePart | URLPart;
+/** Text Part（有 `text` 字段即判别）。 */
+export interface TextPart {
+    text: string;
+}
+/** Data Part（有 `data` 字段即判别；KNP 载荷载体，`mediaType` 可选）。 */
+export interface DataPart {
+    data: Record<string, unknown>;
+    mediaType?: string;
+}
+/** File Part（有 `raw` 字段即判别；`raw` 为 base64，必须带 `mediaType`）。 */
+export interface FilePart {
+    raw: string;
+    mediaType: string;
+}
+/** URL Part（有 `url` 字段即判别）。 */
+export interface URLPart {
+    url: string;
+}
+/** A2A 1.0 Message。 */
+export interface A2AV1Message {
+    role: A2ARole;
+    parts: A2AV1Part[];
+    messageId: string;
+    taskId?: string;
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A2A 1.0 TaskStatus。 */
+export interface A2AV1TaskStatus {
+    state: A2ATaskState;
+    message?: A2AV1Message;
+    timestamp?: string;
+}
+/** A2A 1.0 Artifact。 */
+export interface A2AV1Artifact {
+    parts: A2AV1Part[];
+    artifactId?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A2A 1.0 Task。 */
+export interface A2AV1Task {
+    id: string;
+    status: A2AV1TaskStatus;
+    artifacts?: A2AV1Artifact[];
+    contextId?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist/a2a/v1/types.js

@@ -0,0 +1,62 @@
+/**
+ * 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 1.0 域模型（issue 02）。
+ *
+ * 与 0.3（`src/a2a/client/types.ts`）的差异：
+ * - **统一 Part**：字段存在性判别（有 `text`=Text / `data`=Data / `url`=URL /
+ *   `raw`=File），**无 `kind` 字段**；`mimeType` → `mediaType`；
+ * - **Role**：`ROLE_AGENT` / `ROLE_USER` 命名常量；
+ * - **TaskState**：大写下划线枚举，含 1.0 新增 `REJECTED` / `AUTH_REQUIRED` /
+ *   `UNSPECIFIED`（0.3 的 `unknown` 在 1.0 语义为 `UNSPECIFIED`）。
+ *
+ * 词表单一来源（仿照 `handoff/destination.ts` 纪律）：本文件是 v1 词表的唯一
+ * 权威，编解码/双栈/TCK 全部从这里导入，不散落字符串。
+ */
+/**
+ * A2A 1.0 Role（wire 值 = proto 枚举名，官方 SDK `@a2a-js/sdk` 如此序列化）。
+ * 输入侧兼容小写 `user`/`agent`（server 归一化，见 normalizeV1Role）。
+ */
+export const ROLE_AGENT = "ROLE_AGENT";
+export const ROLE_USER = "ROLE_USER";
+/**
+ * A2A 1.0 TaskState（wire 值 = proto 枚举名 `TASK_STATE_*`，官方 SDK 如此）。
+ * 0.3 `unknown` → 1.0 `TASK_STATE_UNSPECIFIED`。
+ */
+export const A2A_TASK_STATES = [
+    "TASK_STATE_SUBMITTED",
+    "TASK_STATE_WORKING",
+    "TASK_STATE_INPUT_REQUIRED",
+    "TASK_STATE_COMPLETED",
+    "TASK_STATE_CANCELED",
+    "TASK_STATE_FAILED",
+    "TASK_STATE_REJECTED",
+    "TASK_STATE_AUTH_REQUIRED",
+    "TASK_STATE_UNSPECIFIED",
+];
+/** 0.3 内部小写状态 → 1.0 wire TaskState（server 出站用）。 */
+export const LEGACY_TO_V1_STATE = {
+    submitted: "TASK_STATE_SUBMITTED",
+    working: "TASK_STATE_WORKING",
+    "input-required": "TASK_STATE_INPUT_REQUIRED",
+    completed: "TASK_STATE_COMPLETED",
+    canceled: "TASK_STATE_CANCELED",
+    failed: "TASK_STATE_FAILED",
+    unknown: "TASK_STATE_UNSPECIFIED",
+};
+/** 1.0 wire TaskState → 0.3 内部小写状态（client 入站用）。 */
+export const V1_STATE_TO_LEGACY = Object.fromEntries(Object.entries(LEGACY_TO_V1_STATE).map(([legacy, v1]) => [v1, legacy]));
+//# sourceMappingURL=types.js.map

package/dist/a2a/v1/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/a2a/v1/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;GAYG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,YAAqB,CAAC;AAChD,MAAM,CAAC,MAAM,SAAS,GAAG,WAAoB,CAAC;AAG9C;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,sBAAsB;IACtB,oBAAoB;IACpB,2BAA2B;IAC3B,sBAAsB;IACtB,qBAAqB;IACrB,mBAAmB;IACnB,qBAAqB;IACrB,0BAA0B;IAC1B,wBAAwB;CAChB,CAAC;AAGX,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAqC;IAClE,SAAS,EAAE,sBAAsB;IACjC,OAAO,EAAE,oBAAoB;IAC7B,gBAAgB,EAAE,2BAA2B;IAC7C,SAAS,EAAE,sBAAsB;IACjC,QAAQ,EAAE,qBAAqB;IAC/B,MAAM,EAAE,mBAAmB;IAC3B,OAAO,EAAE,wBAAwB;CAClC,CAAC;AAEF,mDAAmD;AACnD,MAAM,CAAC,MAAM,kBAAkB,GAAqC,MAAM,CAAC,WAAW,CACpF,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CACvE,CAAC"}

package/dist/agent/buyer/buyer-tools.js

@@ -58,7 +58,9 @@ function parseIntent(value) {
     if (typeof v.quantity === "number" && Number.isInteger(v.quantity) && v.quantity > 0) {
         out.quantity = v.quantity;
     }
-    if (typeof v.target_unit_price === "number" && Number.isFinite(v.target_unit_price) && v.target_unit_price >= 0) {
+    if (typeof v.target_unit_price === "number" &&
+        Number.isFinite(v.target_unit_price) &&
+        v.target_unit_price >= 0) {
         out.target_unit_price = v.target_unit_price;
     }
     if (Array.isArray(v.preferences))
@@ -80,7 +82,9 @@ function parseConstraints(value) {
     }
     const v = value;
     const out = {};
-    if (typeof v.max_unit_price === "number" && Number.isFinite(v.max_unit_price) && v.max_unit_price >= 0) {
+    if (typeof v.max_unit_price === "number" &&
+        Number.isFinite(v.max_unit_price) &&
+        v.max_unit_price >= 0) {
         out.max_unit_price = v.max_unit_price;
     }
     if (typeof v.max_total_price === "number" && Number.isFinite(v.max_total_price)) {
@@ -140,7 +144,10 @@ function executeSelection(store, now, args) {
         authorization: p.user_instruction,
         score_explanation: candidate.score_explanation ?? null,
         boundary: "未创建订单；非绑定选定不声明价格、库存或交期仍然有效",
-    }, "user", `select:${p.task_id}:${p.candidate_id}:${uuidv7()}`);
+    }, "user", 
+    // 审查 K-L26：幂等键内容寻址（此前 uuidv7 随机，重试产生重复 selected
+    // 事件）。与 transition 键同源，重试去重。
+    `select:${p.task_id}:${p.candidate_id}`);
     store.updateCandidate(p.candidate_id, { candidate_status: "selected" });
     store.transitionTask({
         task_id: p.task_id,
@@ -251,7 +258,12 @@ async function executeNegotiateBuyerTask(deps, args) {
             negotiation_id: result.negotiationId,
             catalog_agent_id: result.catalogAgentId,
         }, "model", eventKey);
-        return { ok: false, task_id: a.task_id, negotiation_id: result.negotiationId, error: result.error };
+        return {
+            ok: false,
+            task_id: a.task_id,
+            negotiation_id: result.negotiationId,
+            error: result.error,
+        };
     }
     const facts = result.facts;
     try {
@@ -313,7 +325,8 @@ async function executeNegotiateBuyerTask(deps, args) {
             steps: result.steps,
             boundary: "非绑定协议 — 不创建订单、不锁库存、不授权支付",
         }, "model", eventKey);
-        await deps.recordNegotiation?.({
+        await deps
+            .recordNegotiation?.({
             negotiationId: result.negotiationId,
             catalogAgentId: result.catalogAgentId,
             sku: facts?.sku ?? sku,
@@ -323,7 +336,8 @@ async function executeNegotiateBuyerTask(deps, args) {
             agreementId: typeof result.agreement?.agreement_id === "string"
                 ? result.agreement.agreement_id
                 : undefined,
-        }).catch(() => undefined); // 记忆尽力而为，失败不阻塞任务推进
+        })
+            .catch(() => undefined); // 记忆尽力而为，失败不阻塞任务推进
         return {
             ok: true,
             task_id: a.task_id,
@@ -500,6 +514,23 @@ export function buildBuyerTools(deps) {
                 .join("\n"));
         },
     };
+    const listPendingApprovals = {
+        name: "list_pending_approvals",
+        label: "列出待审批候选",
+        description: "读取当前仍可执行的写操作审批候选。涉及 /approve 时必须先调用本工具；只允许使用本次返回的 candidate_id，" +
+            "不能从历史对话、任务事件或记忆中复制旧 ID。",
+        parameters: { type: "object", properties: {}, additionalProperties: false },
+        execute: async () => {
+            const pending = deps.approvals?.listPending() ?? [];
+            if (pending.length === 0) {
+                return textResult("当前没有等待批准且仍可执行的写操作候选。候选在重启后会自动失效；如需继续，请重新生成候选。");
+            }
+            return textResult(pending
+                .map((candidate, index) => `${index + 1}. ${candidate.candidate_id} [${candidate.risk}] ${candidate.tool}` +
+                `${candidate.task_id === undefined ? "" : ` task=${candidate.task_id}`}（截止 ${candidate.expires_at}）`)
+                .join("\n"));
+        },
+    };
     const getTask = {
         name: "get_buyer_task",
         label: "任务详情",
@@ -550,9 +581,7 @@ export function buildBuyerTools(deps) {
                     .at(-1);
                 if (negotiated !== undefined) {
                     const p = negotiated.payload;
-                    const fmt = (minor) => typeof minor === "number" && Number.isFinite(minor)
-                        ? (minor / 100).toFixed(2)
-                        : "?";
+                    const fmt = (minor) => typeof minor === "number" && Number.isFinite(minor) ? (minor / 100).toFixed(2) : "?";
                     const sku = typeof p.sku === "string" ? p.sku : "?";
                     const qty = typeof p.quantity === "number" ? String(p.quantity) : "?";
                     const agreement = typeof p.agreement_id === "string" ? p.agreement_id : "?";
@@ -577,7 +606,10 @@ export function buildBuyerTools(deps) {
             type: "object",
             properties: {
                 goal_text: { type: "string", description: "用户原始目标的简洁表达" },
-                intent: { type: "object", description: "结构化意图（category/query_text/city/needed_by/quantity/target_unit_price 等；target_unit_price = 砍价目标单价）" },
+                intent: {
+                    type: "object",
+                    description: "结构化意图（category/query_text/city/needed_by/quantity/target_unit_price 等；target_unit_price = 砍价目标单价）",
+                },
                 constraints: {
                     type: "object",
                     description: "硬约束（max_total_price 私有预算/latest_eta/required_terms/exclude_out_of_stock）",
@@ -606,7 +638,12 @@ export function buildBuyerTools(deps) {
                     // Content-addressed: a model retry with the same args replays the
                     // existing task instead of creating a duplicate.
                     idempotency_key: `create:${createHash("sha256")
-                        .update(JSON.stringify({ goal_text: goalText, intent, constraints, expires_at: expiresAt ?? null }))
+                        .update(JSON.stringify({
+                        goal_text: goalText,
+                        intent,
+                        constraints,
+                        expires_at: expiresAt ?? null,
+                    }))
                         .digest("hex")
                         .slice(0, 16)}`,
                 });
@@ -739,7 +776,13 @@ export function buildBuyerTools(deps) {
                 candidate_id: { type: "string" },
                 rule_type: {
                     type: "string",
-                    enum: ["price_below", "stock_available", "delivery_before", "new_candidate", "periodic_review"],
+                    enum: [
+                        "price_below",
+                        "stock_available",
+                        "delivery_before",
+                        "new_candidate",
+                        "periodic_review",
+                    ],
                 },
                 condition: { type: "object", description: "如 {threshold: 90} 或 {eta_before: RFC3339}" },
                 interval_seconds: { type: "integer" },
@@ -916,6 +959,7 @@ export function buildBuyerTools(deps) {
                     registerPending: deps.registerPending,
                 }, {
                     tool: "start_consultation",
+                    task_id: p.task_id,
                     arguments: args,
                     preconditions: consultationPreconditions(store, p.task_id, p.candidate_id),
                     risk: "send_consultation",
@@ -982,8 +1026,15 @@ export function buildBuyerTools(deps) {
                         ? { catalog_agent_id: p.catalog_agent_id }
                         : {}),
                 };
-                const outcome = await routeWriteCandidate({ mode: deps.mode, approvals: deps.approvals, profile, now, registerPending: deps.registerPending }, {
+                const outcome = await routeWriteCandidate({
+                    mode: deps.mode,
+                    approvals: deps.approvals,
+                    profile,
+                    now,
+                    registerPending: deps.registerPending,
+                }, {
                     tool: "negotiate_buyer_task",
+                    task_id: p.task_id,
                     arguments: args,
                     preconditions: negotiationPreconditions(store, true, p.task_id),
                     risk: "send_negotiation_message",
@@ -1029,9 +1080,15 @@ export function buildBuyerTools(deps) {
         parameters: {
             type: "object",
             properties: {
-                task_id: { type: "string", description: "已达成非绑定协议（selected_nonbinding）的 buyer 任务" },
+                task_id: {
+                    type: "string",
+                    description: "已达成非绑定协议（selected_nonbinding）的 buyer 任务",
+                },
                 display_summary_merchant: { type: "string", description: "展示用商家名（缺省取协议商家）" },
-                display_summary_text: { type: "string", description: "展示用摘要（如“200 units, CNY 8999.00/unit”）" },
+                display_summary_text: {
+                    type: "string",
+                    description: "展示用摘要（如“200 units, CNY 8999.00/unit”）",
+                },
                 expires_in_hours: { type: "number", description: "候选有效期（小时，缺省 24）" },
             },
             required: ["task_id"],
@@ -1067,7 +1124,9 @@ export function buildBuyerTools(deps) {
                 // 协议级去重：同一磋商、同一目的地已交付过 → 拒绝（LLM 重试会生成
                 // 新候选 → 新 digest，绕过 (candidate_id, digest) 幂等键，导致同协议
                 // 二次交付/二次 URL 探测、negotiation_to_handoff_rate 虚高）。
-                const priorDelivery = handoff.ledger.events(agreement.negotiation_id).find((e) => e.event_kind === "handoff_delivered" &&
+                const priorDelivery = handoff.ledger
+                    .events(agreement.negotiation_id)
+                    .find((e) => e.event_kind === "handoff_delivered" &&
                     e.destination?.ref === destination.ref &&
                     e.destination?.type === destination.type);
                 if (priorDelivery !== undefined) {
@@ -1105,8 +1164,15 @@ export function buildBuyerTools(deps) {
                         : {}),
                     requires_user_action: true,
                 });
-                const outcome = await routeWriteCandidate({ mode: deps.mode, approvals: deps.approvals, profile, now: deps.now, registerPending: deps.registerPending }, {
+                const outcome = await routeWriteCandidate({
+                    mode: deps.mode,
+                    approvals: deps.approvals,
+                    profile,
+                    now: deps.now,
+                    registerPending: deps.registerPending,
+                }, {
                     tool: "handoff_agreement",
+                    task_id: p.task_id,
                     arguments: { task_id: p.task_id, candidate },
                     preconditions: { agreement_bound: true },
                     risk: "handoff_delivery",
@@ -1280,6 +1346,7 @@ export function buildBuyerTools(deps) {
     return [
         ...(catalogFirst ? [] : [searchProducts, getProduct]),
         listTasks,
+        listPendingApprovals,
         getTask,
         createTask,
         updateConstraints,
@@ -1384,7 +1451,9 @@ function handoffResultText(result) {
                 status: "already_delivered",
             });
         case "stale":
-            return textResult(`交接未执行：候选已失效（${result.reason}）。需重新生成候选。`, { status: "stale" });
+            return textResult(`交接未执行：候选已失效（${result.reason}）。需重新生成候选。`, {
+                status: "stale",
+            });
         case "probe_failed":
             return textResult(`交接未执行：目的地探测瞬时失败（${result.reason}）。候选保持可用，可重试。`, {
                 status: "probe_failed",
@@ -1404,7 +1473,11 @@ async function executeHandoffForCandidate(deps, args) {
     }
     const agreement = agreementFromTask(deps.store.taskEvents(a.task_id));
     if (agreement === undefined) {
-        return { ok: false, status: "stale", error: "任务记录缺少 agreement 快照，交接中止（fail-closed）" };
+        return {
+            ok: false,
+            status: "stale",
+            error: "任务记录缺少 agreement 快照，交接中止（fail-closed）",
+        };
     }
     // created 事件在审批通过后才落链：被 /reject 的候选不在 Ledger 留下悬空的
     // PROPOSED（此前先落链，/reject 后 /handoff 永远显示"从未获批"的候选，