@harrylabsj/kiwi 0.6.0

package/contracts/interop/knp-data-part-examples.json

@@ -0,0 +1,243 @@
+{
+  "schema": "binding-rc1/data-part-examples/v1",
+  "generated_by": "kiwi dist",
+  "examples": [
+    {
+      "label": "counter_offer",
+      "kind": "message",
+      "message": {
+        "role": "agent",
+        "messageId": "msg_01H5V8KXZqJ7Qp3mN2B6A",
+        "parts": [
+          {
+            "kind": "text",
+            "text": "If we order 200 units, we propose CNY 835.00 per unit."
+          },
+          {
+            "kind": "data",
+            "data": {
+              "knp_envelope": {
+                "capability": "com.harrylabsj.kiwi.shopping.negotiation",
+                "protocol_version": "1.0",
+                "negotiation_id": "neg_01H5V8KXZqJ7Qp3mN2B6A",
+                "exchange_id": "ex_01H5V8KXZqJ7Qp3mN2B6A",
+                "created_at": "2026-08-05T12:00:00Z",
+                "message_id": "msg_01H5V8KXZqJ7Qp3mN2B6A",
+                "in_reply_to": "msg_00H5V8KXZqJ7Qp3mN2B6A",
+                "actor": "buyer",
+                "action": "counter_offer",
+                "payload": {
+                  "type": "counter_offer",
+                  "offer_id": "off_02H5V8KXZqJ7Qp3mN2B6A",
+                  "responding_to_offer_id": "off_01H5V8KXZqJ7Qp3mN2B6A",
+                  "proposed_terms": {
+                    "items": [
+                      {
+                        "sku": "SKU-001",
+                        "quantity": {
+                          "value": 200,
+                          "unit": "piece"
+                        },
+                        "unit_price": {
+                          "currency": "CNY",
+                          "amount_minor": 83500
+                        }
+                      }
+                    ]
+                  }
+                },
+                "public_message": "If we order 200 units, we propose CNY 835.00 per unit.",
+                "digest": "sha256:87517fc5c7d13be7abba1e02349632e891aa1062da9339e90dd6249c0e985295"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "label": "offer",
+      "kind": "message",
+      "message": {
+        "role": "agent",
+        "messageId": "msg_02H5V8KXZqJ7Qp3mN2B6A",
+        "parts": [
+          {
+            "kind": "text",
+            "text": "We offer CNY 850.00 per unit, delivery before 2026-08-20."
+          },
+          {
+            "kind": "data",
+            "data": {
+              "knp_envelope": {
+                "capability": "com.harrylabsj.kiwi.shopping.negotiation",
+                "protocol_version": "1.0",
+                "negotiation_id": "neg_01H5V8KXZqJ7Qp3mN2B6A",
+                "exchange_id": "ex_01H5V8KXZqJ7Qp3mN2B6A",
+                "created_at": "2026-08-05T12:00:00Z",
+                "message_id": "msg_02H5V8KXZqJ7Qp3mN2B6A",
+                "in_reply_to": "msg_00H5V8KXZqJ7Qp3mN2B6A",
+                "actor": "merchant",
+                "action": "offer",
+                "payload": {
+                  "type": "offer",
+                  "offer_id": "off_01H5V8KXZqJ7Qp3mN2B6A",
+                  "terms": {
+                    "items": [
+                      {
+                        "sku": "SKU-001",
+                        "quantity": {
+                          "value": 200,
+                          "unit": "piece"
+                        },
+                        "unit_price": {
+                          "currency": "CNY",
+                          "amount_minor": 85000
+                        }
+                      }
+                    ],
+                    "fulfillment_terms": {
+                      "delivery_before": "2026-08-20T18:00:00Z"
+                    },
+                    "valid_until": "2026-08-06T12:00:00Z"
+                  }
+                },
+                "public_message": "We offer CNY 850.00 per unit, delivery before 2026-08-20.",
+                "digest": "sha256:99dfb819f5668835005582cfb1db4992d5bd13fa9059e4b2298dda1c466b5742"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "label": "inquiry",
+      "kind": "message",
+      "message": {
+        "role": "agent",
+        "messageId": "msg_03H5V8KXZqJ7Qp3mN2B6A",
+        "parts": [
+          {
+            "kind": "text",
+            "text": "请问这款商品的预计交付时间？"
+          },
+          {
+            "kind": "data",
+            "data": {
+              "knp_envelope": {
+                "capability": "com.harrylabsj.kiwi.shopping.negotiation",
+                "protocol_version": "1.0",
+                "negotiation_id": "neg_01H5V8KXZqJ7Qp3mN2B6A",
+                "exchange_id": "ex_01H5V8KXZqJ7Qp3mN2B6A",
+                "created_at": "2026-08-05T12:00:00Z",
+                "message_id": "msg_03H5V8KXZqJ7Qp3mN2B6A",
+                "actor": "buyer",
+                "action": "inquiry",
+                "payload": {
+                  "type": "inquiry",
+                  "subject": {
+                    "sku": "SKU-001"
+                  },
+                  "questions": [
+                    {
+                      "code": "delivery.estimated_date"
+                    }
+                  ]
+                },
+                "digest": "sha256:a08539767c6fc46ddc8111fd0b1f320e85978dd164c4ed7bf592646305e91736"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "label": "accept_nonbinding",
+      "kind": "message",
+      "message": {
+        "role": "agent",
+        "messageId": "msg_04H5V8KXZqJ7Qp3mN2B6A",
+        "parts": [
+          {
+            "kind": "data",
+            "data": {
+              "knp_envelope": {
+                "capability": "com.harrylabsj.kiwi.shopping.negotiation",
+                "protocol_version": "1.0",
+                "negotiation_id": "neg_01H5V8KXZqJ7Qp3mN2B6A",
+                "exchange_id": "ex_01H5V8KXZqJ7Qp3mN2B6A",
+                "created_at": "2026-08-05T12:00:00Z",
+                "message_id": "msg_04H5V8KXZqJ7Qp3mN2B6A",
+                "in_reply_to": "msg_01H5V8KXZqJ7Qp3mN2B6A",
+                "actor": "buyer",
+                "action": "accept_nonbinding",
+                "payload": {
+                  "type": "accept_nonbinding",
+                  "offer_id": "off_01H5V8KXZqJ7Qp3mN2B6A",
+                  "terms_digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a"
+                },
+                "digest": "sha256:0231490ea2ff95b8d9a230f2dfb8901ade73f56f0e1f71921bed4157b89c69da"
+              }
+            }
+          }
+        ]
+      }
+    },
+    {
+      "label": "task_result",
+      "kind": "task",
+      "task": {
+        "taskId": "task_01H5V8KXZqJ7Qp3mN2B6A",
+        "status": {
+          "state": "completed",
+          "message": {
+            "role": "agent",
+            "messageId": "msg_05H5V8KXZqJ7Qp3mN2B6A",
+            "parts": [
+              {
+                "kind": "data",
+                "data": {
+                  "knp_envelope": {
+                    "capability": "com.harrylabsj.kiwi.shopping.negotiation",
+                    "protocol_version": "1.0",
+                    "negotiation_id": "neg_01H5V8KXZqJ7Qp3mN2B6A",
+                    "exchange_id": "ex_01H5V8KXZqJ7Qp3mN2B6A",
+                    "created_at": "2026-08-05T12:00:00Z",
+                    "message_id": "msg_05H5V8KXZqJ7Qp3mN2B6A",
+                    "in_reply_to": "msg_01H5V8KXZqJ7Qp3mN2B6A",
+                    "actor": "merchant",
+                    "action": "offer",
+                    "payload": {
+                      "type": "offer",
+                      "offer_id": "off_01H5V8KXZqJ7Qp3mN2B6A",
+                      "terms": {
+                        "items": [
+                          {
+                            "sku": "SKU-001",
+                            "quantity": {
+                              "value": 200,
+                              "unit": "piece"
+                            },
+                            "unit_price": {
+                              "currency": "CNY",
+                              "amount_minor": 85000
+                            }
+                          }
+                        ],
+                        "fulfillment_terms": {
+                          "delivery_before": "2026-08-20T18:00:00Z"
+                        },
+                        "valid_until": "2026-08-06T12:00:00Z"
+                      }
+                    },
+                    "public_message": "异步任务的 offer 结果。",
+                    "digest": "sha256:faf538b5cd7eff5e2e9eae85774d9f0ab98fe317dff7a52a5fb57a5d3d94be82"
+                  }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/contracts/kiwi-catalog/1.0/agent-record.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "kiwi-catalog agent record",
+  "description": "kiwi-catalog /v1/agents 的 CatalogAgentRecord wire 形状（产品文档 v0.3 §6/§7）。public-only：register 与响应均不得携带私有经营数据（完成定义 #8）。三正交状态域（VerificationLevel / FreshnessState / AdministrativeState）各自独立，不得坍缩为单一状态机。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "catalog_agent_id",
+    "principal_type",
+    "display_name",
+    "canonical_domain",
+    "hosting_mode",
+    "verification_level",
+    "freshness_state",
+    "administrative_state",
+    "created_at",
+    "updated_at"
+  ],
+  "properties": {
+    "catalog_agent_id": { "type": "string", "minLength": 1 },
+    "principal_type": { "enum": ["buyer", "merchant"] },
+    "merchant_id": { "type": "string", "minLength": 1 },
+    "display_name": { "type": "string", "minLength": 1 },
+    "canonical_domain": { "type": "string", "minLength": 1 },
+    "agent_card_url": { "type": "string", "pattern": "^https?://\\S+$" },
+    "ucp_profile_url": { "type": "string", "pattern": "^https?://\\S+$" },
+    "protocols": {
+      "type": "object",
+      "additionalProperties": { "type": "array", "items": { "type": "string" } }
+    },
+    "capabilities": { "type": "array", "items": { "type": "string" } },
+    "skills": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["skill_id", "name"],
+        "properties": {
+          "skill_id": { "type": "string", "minLength": 1 },
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string" },
+          "tags": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "hosting_mode": {
+      "enum": ["direct", "hosted", "hybrid", "unknown", "direct_only", "hosted_only"]
+    },
+    "handoff_destination_types": {
+      "description": "KTH destination_type 精确词表（单一来源，禁止 supports_* 平行词表）",
+      "type": "array",
+      "items": {
+        "enum": [
+          "ucp_checkout",
+          "ucp_order",
+          "external_checkout_url",
+          "merchant_checkout_session",
+          "platform_deep_link",
+          "buyer_erp_request",
+          "procurement_request",
+          "purchase_order_draft",
+          "quote_document",
+          "merchant_contact",
+          "sales_handoff"
+        ]
+      }
+    },
+    "verification_level": {
+      "enum": ["discovered", "profile_valid", "domain_verified", "agent_verified", "commerce_verified"]
+    },
+    "freshness_state": { "enum": ["fresh", "stale", "unreachable"] },
+    "administrative_state": { "enum": ["active", "suspended", "rejected"] },
+    "last_verified_at": { "type": "string", "minLength": 1 },
+    "fresh_until": { "type": "string", "minLength": 1 },
+    "created_at": { "type": "string", "minLength": 1 },
+    "updated_at": { "type": "string", "minLength": 1 }
+  }
+}

package/contracts/kiwi-catalog/1.0/listing-record.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "listing-record.schema.json",
+  "title": "kiwi-catalog listing record",
+  "description": "kiwi-catalog /v1/listings 的 ListingRecord wire 形状（产品文档 kiwi-catalog v0.4 §4/§5/§9）。public-only discovery projection：不得携带 merchant cost / floor price / 私有库存 / 凭据 / 客户数据（v0.4 §4.2 Forbidden Fields）。listing freshness 与 Agent freshness 分离：本 schema 用大写 listing_freshness_state（FRESH/STALE），与 agent-record 的小写 freshness_state（fresh/stale/unreachable）拼写区分，禁止混用。CapabilityListing 不得虚构 SKU，也不携带 handoff_destination_types。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "listing_id",
+    "listing_type",
+    "owner_agent_id",
+    "merchant_id",
+    "title",
+    "category",
+    "listing_digest",
+    "publication_state",
+    "listing_freshness_state",
+    "published_at",
+    "updated_at",
+    "fresh_until"
+  ],
+  "if": {
+    "properties": { "listing_type": { "const": "product" } },
+    "required": ["listing_type"]
+  },
+  "then": { "required": ["source_product_ref"] },
+  "else": {
+    "not": { "required": ["handoff_destination_types"] }
+  },
+  "properties": {
+    "listing_id": { "type": "string", "pattern": "^lst_" },
+    "listing_type": { "enum": ["product", "capability"] },
+    "owner_agent_id": { "type": "string", "minLength": 1 },
+    "merchant_id": { "type": "string", "minLength": 1 },
+    "source_product_ref": { "type": "string", "minLength": 1 },
+    "source_revision": { "type": "string", "minLength": 1 },
+    "title": { "type": "string", "minLength": 1 },
+    "summary": { "type": "string" },
+    "category": { "type": "string", "minLength": 1 },
+    "brand": { "type": "string", "minLength": 1 },
+    "attributes": {
+      "type": "object",
+      "additionalProperties": { "type": ["string", "number", "boolean"] },
+      "maxProperties": 64
+    },
+    "regions": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "commercial_hints": {
+      "description": "discovery hints，不是 KNP Offer（v0.4 §4.1）；authority 仍在 Direct A2A 阶段确认",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "moq": { "type": "integer", "minimum": 1 },
+        "price_range_hint": { "type": "string", "minLength": 1 },
+        "availability_hint": { "type": "string", "minLength": 1 },
+        "lead_time_hint": { "type": "string", "minLength": 1 },
+        "supports_bulk_quote": { "type": "boolean" },
+        "supports_customization": { "type": "boolean" },
+        "fulfillment_regions": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "handoff_destination_types": {
+      "description": "仅 ProductListing 允许；精确 KTH destination_type 词表（单一来源，禁止 supports_* 平行词表）",
+      "type": "array",
+      "items": {
+        "enum": [
+          "ucp_checkout",
+          "ucp_order",
+          "external_checkout_url",
+          "merchant_checkout_session",
+          "platform_deep_link",
+          "buyer_erp_request",
+          "procurement_request",
+          "purchase_order_draft",
+          "quote_document",
+          "merchant_contact",
+          "sales_handoff"
+        ]
+      }
+    },
+    "listing_digest": { "type": "string", "minLength": 1 },
+    "publication_state": { "enum": ["ACTIVE", "WITHDRAWN", "SUSPENDED"] },
+    "listing_freshness_state": { "enum": ["FRESH", "STALE"] },
+    "published_at": { "type": "string", "minLength": 1 },
+    "updated_at": { "type": "string", "minLength": 1 },
+    "fresh_until": { "type": "string", "minLength": 1 }
+  }
+}

package/contracts/kiwi-catalog/1.0/listing-search-result.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "listing-search-result.schema.json",
+  "title": "kiwi-catalog listing search result",
+  "description": "kiwi-catalog /v1/listings/search 的单个结果形状（产品文档 kiwi-catalog v0.4 §9）。同时返回“商品/能力”与“谁可以被联系”：listing（$ref listing-record）+ merchant/agent 投影。authority 恒为 discovery_projection、requires_direct_confirmation 恒为 true（v0.4 CD #24）：Catalog 只负责召回，Merchant Agent 负责确认；hint 永不视为 Offer/库存预留（v0.4 §3 Source of Truth Boundary）。",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "listing",
+    "merchant",
+    "agent",
+    "listing_freshness_state",
+    "authority",
+    "requires_direct_confirmation"
+  ],
+  "properties": {
+    "listing": { "$ref": "listing-record.schema.json" },
+    "merchant": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["merchant_id", "display_name"],
+      "properties": {
+        "merchant_id": { "type": "string", "minLength": 1 },
+        "display_name": { "type": "string", "minLength": 1 }
+      }
+    },
+    "agent": {
+      "description": "owner Agent 当前投影（join 自 catalog_agents）；Buyer 后续按 owner_agent_id → getRecord → fresh verify，本投影不复制 A2A endpoint（v0.4 §11）",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "catalog_agent_id",
+        "verification_level",
+        "freshness_state",
+        "administrative_state"
+      ],
+      "properties": {
+        "catalog_agent_id": { "type": "string", "minLength": 1 },
+        "verification_level": {
+          "enum": ["discovered", "profile_valid", "domain_verified", "agent_verified", "commerce_verified"]
+        },
+        "freshness_state": { "enum": ["fresh", "stale", "unreachable"] },
+        "administrative_state": { "enum": ["active", "suspended", "rejected"] }
+      }
+    },
+    "listing_freshness_state": { "enum": ["FRESH", "STALE"] },
+    "authority": { "enum": ["discovery_projection"] },
+    "requires_direct_confirmation": { "const": true },
+    "match": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "matched_category": { "type": "boolean" },
+        "matched_region": { "type": "boolean" },
+        "matched_brand": { "type": "boolean" },
+        "score": { "type": "number" }
+      }
+    }
+  }
+}