@harrylabsj/kiwi 0.6.0

package/dist/discovery/catalog-source/kiwi-record.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+/** 折叠优先级：行政 > 可达性 > 新鲜度 > 验证级别。 */
+function foldVerificationStatus(level, freshness, admin) {
+    if (admin === "rejected")
+        return "rejected";
+    if (admin === "suspended")
+        return "suspended";
+    if (freshness === "unreachable")
+        return "unreachable";
+    if (freshness === "stale")
+        return "stale";
+    return level;
+}
+/**
+ * 三态域 record → CandidateAgent DTO 1.0 共享候选形状。
+ * 注意：handoff_destination_types **不进入** CandidateAgent（DTO 1.0
+ * additionalProperties: false）；需要 handoff 词表的消费方走 searchRecords。
+ */
+export function normalizeCatalogAgent(record) {
+    const candidate = {
+        catalog_agent_id: record.catalog_agent_id,
+        merchant: {
+            id: record.merchant_id ?? record.catalog_agent_id,
+            name: record.display_name,
+            ...(record.canonical_domain !== undefined ? { domain: record.canonical_domain } : {}),
+        },
+        ...(record.agent_card_url !== undefined || record.ucp_profile_url !== undefined
+            ? {
+                discovery: {
+                    ...(record.agent_card_url !== undefined ? { agent_card_url: record.agent_card_url } : {}),
+                    ...(record.ucp_profile_url !== undefined ? { ucp_profile_url: record.ucp_profile_url } : {}),
+                },
+            }
+            : {}),
+        ...(record.protocols !== undefined
+            ? { protocols: record.protocols }
+            : {}),
+        ...(record.capabilities !== undefined ? { capabilities: [...record.capabilities] } : {}),
+        ...(record.skills !== undefined
+            ? {
+                skills: record.skills.map((s) => ({
+                    skill_id: s.skill_id,
+                    name: s.name,
+                    ...(s.description !== undefined ? { description: s.description } : {}),
+                    ...(s.tags !== undefined ? { tags: [...s.tags] } : {}),
+                })),
+            }
+            : {}),
+        verification: {
+            status: foldVerificationStatus(record.verification_level, record.freshness_state, record.administrative_state),
+            ...(record.last_verified_at !== undefined ? { last_verified_at: record.last_verified_at } : {}),
+        },
+        hosting: { mode: record.hosting_mode },
+        contract: { name: "candidate-agent", version: "1.0" },
+    };
+    return candidate;
+}
+//# sourceMappingURL=kiwi-record.js.map

package/dist/discovery/catalog-source/kiwi-record.js.map

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

package/dist/discovery/catalog-source/kiwi-schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { CatalogAgentRecord, ListingRecord, ListingSearchResult } from "./kiwi-record.js";
+/**
+ * 校验一个 agent record。通过则返回类型化的 CatalogAgentRecord；失败抛
+ * contract_violation（fail-closed）。错误信息带 JSON Pointer 路径便于诊断。
+ */
+export declare function validateCatalogAgentRecord(value: unknown): CatalogAgentRecord;
+/**
+ * 校验一个 listing record（v0.4 §4/§5 wire 形状）。失败抛 contract_violation
+ * （fail-closed）。private-only 字段（cost/floor/credentials）在 schema 层
+ * additionalProperties: false 拒绝。
+ */
+export declare function validateListingRecord(value: unknown): ListingRecord;
+/**
+ * 校验一个 listing search result（v0.4 §9 形状；CD #24：authority 恒为
+ * discovery_projection、requires_direct_confirmation 恒为 true，schema 层锁定）。
+ * listing 字段经 $ref 复用 listing-record.schema.json（不双份维护字段）。
+ */
+export declare function validateListingSearchResult(value: unknown): ListingSearchResult;

package/dist/discovery/catalog-source/kiwi-schema.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+/**
+ * CatalogAgentRecord —— ajv 校验（fail-closed，与 candidate-agent DTO 同模式）。
+ *
+ * Schema canonical 来源：contracts/kiwi-catalog/1.0/agent-record.schema.json
+ * （draft-07，additionalProperties: false —— 未知/私有字段在 schema 层即拒绝，
+ * 完成定义 #8）。KiwiCatalogSource 对每个收到的 record 做校验；失败 →
+ * CatalogSourceError("contract_violation")，绝不把未校验对象当合法候选使用。
+ */
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { CatalogSourceError } from "./errors.js";
+const require = createRequire(import.meta.url);
+const Ajv = require("ajv");
+/** 从本模块定位仓库根：src/discovery/catalog-source/kiwi-schema.ts → <root>。 */
+function packageRoot() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, "..", "..", "..");
+}
+function loadSchema(name) {
+    const file = path.join(packageRoot(), "contracts", "kiwi-catalog", "1.0", name);
+    return JSON.parse(readFileSync(file, "utf-8"));
+}
+let compiled;
+function getValidator() {
+    if (compiled !== undefined)
+        return compiled;
+    compiled = new Ajv({ allErrors: true }).compile(loadSchema("agent-record.schema.json"));
+    return compiled;
+}
+let listingRecordValidator;
+function getListingRecordValidator() {
+    if (listingRecordValidator !== undefined)
+        return listingRecordValidator;
+    // allowUnionTypes：attributes 值允许 string|number|boolean（strictTypes 仅静态检查，运行时校验仍严格）
+    listingRecordValidator = new Ajv({ allErrors: true, allowUnionTypes: true }).compile(loadSchema("listing-record.schema.json"));
+    return listingRecordValidator;
+}
+let listingSearchResultValidator;
+function getListingSearchResultValidator() {
+    if (listingSearchResultValidator !== undefined)
+        return listingSearchResultValidator;
+    const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+    const recordSchema = loadSchema("listing-record.schema.json");
+    ajv.addSchema(recordSchema, "listing-record.schema.json");
+    listingSearchResultValidator = ajv.compile(loadSchema("listing-search-result.schema.json"));
+    return listingSearchResultValidator;
+}
+/**
+ * 校验一个 agent record。通过则返回类型化的 CatalogAgentRecord；失败抛
+ * contract_violation（fail-closed）。错误信息带 JSON Pointer 路径便于诊断。
+ */
+export function validateCatalogAgentRecord(value) {
+    const validate = getValidator();
+    if (validate(value))
+        return value;
+    const errors = (validate.errors ?? [])
+        .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`.trim())
+        .join("; ");
+    throw new CatalogSourceError("contract_violation", `CatalogAgentRecord failed agent-record schema validation: ${errors}`);
+}
+/**
+ * 校验一个 listing record（v0.4 §4/§5 wire 形状）。失败抛 contract_violation
+ * （fail-closed）。private-only 字段（cost/floor/credentials）在 schema 层
+ * additionalProperties: false 拒绝。
+ */
+export function validateListingRecord(value) {
+    const validate = getListingRecordValidator();
+    if (validate(value))
+        return value;
+    const errors = (validate.errors ?? [])
+        .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`.trim())
+        .join("; ");
+    throw new CatalogSourceError("contract_violation", `ListingRecord failed listing-record schema validation: ${errors}`);
+}
+/**
+ * 校验一个 listing search result（v0.4 §9 形状；CD #24：authority 恒为
+ * discovery_projection、requires_direct_confirmation 恒为 true，schema 层锁定）。
+ * listing 字段经 $ref 复用 listing-record.schema.json（不双份维护字段）。
+ */
+export function validateListingSearchResult(value) {
+    const validate = getListingSearchResultValidator();
+    if (validate(value))
+        return value;
+    const errors = (validate.errors ?? [])
+        .map((e) => `${e.instancePath || "/"} ${e.message ?? "invalid"}`.trim())
+        .join("; ");
+    throw new CatalogSourceError("contract_violation", `ListingSearchResult failed listing-search-result schema validation: ${errors}`);
+}
+//# sourceMappingURL=kiwi-schema.js.map

package/dist/discovery/catalog-source/kiwi-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kiwi-schema.js","sourceRoot":"","sources":["../../../src/discovery/catalog-source/kiwi-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;GAOG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAGxB,CAAC;AAEF,sEAAsE;AACtE,SAAS,WAAW;IAClB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAChF,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAA4B,CAAC;AAC5E,CAAC;AAED,IAAI,QAAsC,CAAC;AAE3C,SAAS,YAAY;IACnB,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,QAAQ,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,0BAA0B,CAAC,CAAC,CAAC;IACxF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,IAAI,sBAAoD,CAAC;AAEzD,SAAS,yBAAyB;IAChC,IAAI,sBAAsB,KAAK,SAAS;QAAE,OAAO,sBAAsB,CAAC;IACxE,mFAAmF;IACnF,sBAAsB,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAClF,UAAU,CAAC,4BAA4B,CAAC,CACzC,CAAC;IACF,OAAO,sBAAsB,CAAC;AAChC,CAAC;AAED,IAAI,4BAA0D,CAAC;AAE/D,SAAS,+BAA+B;IACtC,IAAI,4BAA4B,KAAK,SAAS;QAAE,OAAO,4BAA4B,CAAC;IACpF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,UAAU,CAAC,4BAA4B,CAAC,CAAC;IAC9D,GAAG,CAAC,SAAS,CAAC,YAAY,EAAE,4BAA4B,CAAC,CAAC;IAC1D,4BAA4B,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,mCAAmC,CAAC,CAAC,CAAC;IAC5F,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAA2B,CAAC;IACxD,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,kBAAkB,CAC1B,oBAAoB,EACpB,6DAA6D,MAAM,EAAE,CACtE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,MAAM,QAAQ,GAAG,yBAAyB,EAAE,CAAC;IAC7C,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAAsB,CAAC;IACnD,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,kBAAkB,CAC1B,oBAAoB,EACpB,0DAA0D,MAAM,EAAE,CACnE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAc;IACxD,MAAM,QAAQ,GAAG,+BAA+B,EAAE,CAAC;IACnD,IAAI,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,KAA4B,CAAC;IACzD,MAAM,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;SACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC;SACvE,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,IAAI,kBAAkB,CAC1B,oBAAoB,EACpB,uEAAuE,MAAM,EAAE,CAChF,CAAC;AACJ,CAAC"}

package/dist/discovery/catalog-source/kiwi-source.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 { CatalogSourceDeps } from "./source.js";
+import { type CatalogAgentRecord, type KiwiCatalogSearchQuery, type KiwiListingSearchQuery, type ListingRecord, type ListingSearchResult } from "./kiwi-record.js";
+import type { CandidateAgent } from "./types.js";
+export declare class KiwiCatalogSource {
+    private readonly baseUrl;
+    private readonly deps;
+    constructor(deps: CatalogSourceDeps);
+    /** 核心请求：超时 / HTTP / 网络失败统一映射为 CatalogSourceError。 */
+    private getJson;
+    /** 搜索 record（新 API，支持三态域 + handoff 词表过滤）。 */
+    searchRecords(query?: KiwiCatalogSearchQuery): Promise<CatalogAgentRecord[]>;
+    /** 按 catalog_agent_id 取单个 record。 */
+    getRecord(catalogAgentId: string): Promise<CatalogAgentRecord>;
+    /** 搜索候选（CatalogSource 接口面：三态域折叠为 CandidateAgent 共享形状）。 */
+    searchCandidates(query?: KiwiCatalogSearchQuery): Promise<CandidateAgent[]>;
+    /** 取单个候选（CatalogSource 接口面）。 */
+    getCandidate(catalogAgentId: string): Promise<CandidateAgent>;
+    /** 搜索 listing（v0.4 §8；rev1.5 CD #22/#24）。分页完整拉取，跨页去重；
+     *  limit 是总返回上限而非页大小（历史教训：--limit N 曾返回全目录）。 */
+    searchListings(query?: KiwiListingSearchQuery): Promise<ListingSearchResult[]>;
+    /** 按 listing_id 取单个 listing record（publisher 自查/详情）。 */
+    getListing(listingId: string): Promise<ListingRecord>;
+}

package/dist/discovery/catalog-source/kiwi-source.js

@@ -0,0 +1,318 @@
+/**
+ * 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.
+ */
+/**
+ * KiwiCatalogSource —— 消费 kiwi-catalog 独立服务的新 API（产品文档 v0.3 §9）。
+ *
+ *   GET {baseUrl}/v1/agents/search   → {results: [CatalogAgentRecord…], next_cursor?}
+ *   GET {baseUrl}/v1/agents/{id}     → {agent: CatalogAgentRecord}
+ *
+ * 每个响应元素按 contracts/kiwi-catalog/1.0/agent-record.schema.json 校验（#8 在
+ * schema 层强制：additionalProperties: false，私有字段进不来）。任何校验 / HTTP /
+ * 网络 / 超时失败抛 CatalogSourceError（fail-closed），不静默容错、不自动降级。
+ *
+ * 与 ShoppingCliCatalogSource 的关系：后者消费 legacy `/v1/agent-catalog/*`
+ * （DTO 1.0 直接）；本类消费新 `/v1/agents/*`（三正交状态域 record），经
+ * normalizeCatalogAgent 折叠为共享 CandidateAgent 形状，两者都满足
+ * `CatalogSource` 接口（resolve.ts 的 resolveViaCatalog 可互换）。
+ *
+ * `handoff_destination_types` 搜索词表从 src/handoff/destination.ts import
+ * （单一来源，禁止 supports_* 平行词表；架构 rev1.4.1 §35A 一致性原则）。
+ */
+import { CatalogSourceError } from "./errors.js";
+import { isRedirectResponse, readJsonBody, SafeHttpError } from "../../net/safe-http.js";
+import { validateBaseUrl } from "./source.js";
+import { validateCatalogAgentRecord, validateListingRecord, validateListingSearchResult } from "./kiwi-schema.js";
+import { normalizeCatalogAgent, } from "./kiwi-record.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** 分页拉取上限（防御服务端游标不前进/循环；100 页 × 页大小已远超目录规模）。 */
+const MAX_SEARCH_PAGES = 100;
+const KIWI_SEARCH_QUERY_KEYS = [
+    "q",
+    "capability",
+    "protocol",
+    "hosting_mode",
+    "verification_level",
+    "freshness_state",
+    "administrative_state",
+    "handoff_destination_types",
+    "limit",
+    "cursor",
+];
+/** listing 搜索查询键白名单（v0.4 §8；未知键 fail-closed invalid_input）。 */
+const KIWI_LISTING_SEARCH_QUERY_KEYS = [
+    "q",
+    "listing_type",
+    "category",
+    "brand",
+    "region",
+    "tag",
+    "min_moq",
+    "max_moq",
+    "supports_bulk_quote",
+    "supports_customization",
+    "freshness_state",
+    "handoff_destination_type",
+    "limit",
+    "cursor",
+];
+/**
+ * 序列化富搜索查询。未知键 → invalid_input（fail-closed，不静默丢弃）。
+ * handoff_destination_types 按 KTH destination_type 枚举逐值校验后以逗号连接。
+ */
+function buildSearchQuery(query) {
+    for (const key of Object.keys(query)) {
+        if (!KIWI_SEARCH_QUERY_KEYS.includes(key)) {
+            throw new CatalogSourceError("invalid_input", `unknown kiwi-catalog search query key: "${key}"`);
+        }
+    }
+    if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit <= 0)) {
+        throw new CatalogSourceError("invalid_input", `kiwi-catalog search limit must be a positive integer (got ${query.limit})`);
+    }
+    const entries = [];
+    const push = (key, value) => {
+        if (value !== undefined)
+            entries.push([key, value]);
+    };
+    push("q", query.q);
+    push("capability", query.capability);
+    push("protocol", query.protocol);
+    push("hosting_mode", query.hosting_mode);
+    push("verification_level", query.verification_level);
+    push("freshness_state", query.freshness_state);
+    push("administrative_state", query.administrative_state);
+    if (query.handoff_destination_types !== undefined) {
+        if (query.handoff_destination_types.length === 0) {
+            throw new CatalogSourceError("invalid_input", "handoff_destination_types must be a non-empty array of KTH destination_type values");
+        }
+        entries.push(["handoff_destination_types", [...query.handoff_destination_types].join(",")]);
+    }
+    if (query.limit !== undefined)
+        push("limit", String(query.limit));
+    push("cursor", query.cursor);
+    return new URLSearchParams(entries).toString();
+}
+export class KiwiCatalogSource {
+    baseUrl;
+    deps;
+    constructor(deps) {
+        this.baseUrl = validateBaseUrl(deps.baseUrl);
+        this.deps = deps;
+    }
+    /** 核心请求：超时 / HTTP / 网络失败统一映射为 CatalogSourceError。 */
+    async getJson(requestPath) {
+        const fetchImpl = this.deps.fetchImpl ?? globalThis.fetch;
+        const timeoutMs = this.deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const url = `${this.baseUrl}${requestPath}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                // 出站加固：绝不跟随重定向（3xx 目标不经过校验，且可能转发 Bearer 头）。
+                redirect: "manual",
+                signal: controller.signal,
+                headers: {
+                    accept: "application/json",
+                    ...(this.deps.authToken !== undefined
+                        ? { authorization: `Bearer ${this.deps.authToken}` }
+                        : {}),
+                },
+            });
+        }
+        catch (err) {
+            const name = err?.name;
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new CatalogSourceError("request_failed", name === "AbortError"
+                ? `kiwi-catalog request timed out after ${timeoutMs}ms: ${url}`
+                : `kiwi-catalog request failed: ${url} (${detail})`);
+        }
+        if (isRedirectResponse(response)) {
+            throw new CatalogSourceError("request_failed", `kiwi-catalog request must not follow redirects (HTTP ${response.status} from ${url})`);
+        }
+        if (!response.ok) {
+            throw new CatalogSourceError("request_failed", `kiwi-catalog request returned HTTP ${response.status} from ${url}`);
+        }
+        let raw;
+        try {
+            // 响应体读取在超时覆盖内 + 大小上限（出站加固）。
+            raw = await readJsonBody(response, { signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new CatalogSourceError("request_failed", `kiwi-catalog request timed out after ${timeoutMs}ms while reading response: ${url}`);
+            }
+            throw new CatalogSourceError("response_invalid", err instanceof SafeHttpError && err.code === "response_too_large"
+                ? `kiwi-catalog response from ${url}: ${err.message}`
+                : `kiwi-catalog response from ${url} is not valid JSON`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        return raw;
+    }
+    /** 搜索 record（新 API，支持三态域 + handoff 词表过滤）。 */
+    async searchRecords(query = {}) {
+        // 分页完整拉取：服务端响应带 next_cursor 时翻页直到无游标或达到 limit
+        // 总量（limit 是总返回上限而非页大小——历史教训：只当页大小用会让
+        // --limit 5 返回全目录）；跨页 catalog_agent_id 去重。
+        const records = [];
+        const seen = new Set();
+        const limit = query.limit;
+        let cursor;
+        for (let page = 0; page < MAX_SEARCH_PAGES; page++) {
+            // 先构造查询（buildSearchQuery 校验 limit 为正整数，fail-closed），
+            // 再判总量封顶——提前 break 会绕过校验（limit=0 必须 reject）。
+            const qs = buildSearchQuery({ ...query, ...(cursor !== undefined ? { cursor } : {}) });
+            if (limit !== undefined && records.length >= limit)
+                break;
+            const raw = await this.getJson(`/v1/agents/search${qs.length > 0 ? `?${qs}` : ""}`);
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new CatalogSourceError("response_invalid", "kiwi-catalog search response must be a JSON object");
+            }
+            const body = raw;
+            if (!Array.isArray(body.results)) {
+                throw new CatalogSourceError("response_invalid", 'kiwi-catalog search response is missing array field "results"');
+            }
+            for (const element of body.results) {
+                if (limit !== undefined && records.length >= limit)
+                    break;
+                const record = validateCatalogAgentRecord(element);
+                if (seen.has(record.catalog_agent_id))
+                    continue;
+                seen.add(record.catalog_agent_id);
+                records.push(record);
+            }
+            const next = body.next_cursor;
+            if (typeof next !== "string" || next === "")
+                break;
+            cursor = next;
+        }
+        return limit !== undefined ? records.slice(0, limit) : records;
+    }
+    /** 按 catalog_agent_id 取单个 record。 */
+    async getRecord(catalogAgentId) {
+        if (typeof catalogAgentId !== "string" || catalogAgentId.length === 0) {
+            throw new CatalogSourceError("invalid_input", "catalogAgentId must be a non-empty string");
+        }
+        const raw = await this.getJson(`/v1/agents/${encodeURIComponent(catalogAgentId)}`);
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new CatalogSourceError("response_invalid", "kiwi-catalog get response must be a JSON object");
+        }
+        const body = raw;
+        if (body.agent === undefined) {
+            throw new CatalogSourceError("response_invalid", 'kiwi-catalog get response is missing field "agent"');
+        }
+        return validateCatalogAgentRecord(body.agent);
+    }
+    /** 搜索候选（CatalogSource 接口面：三态域折叠为 CandidateAgent 共享形状）。 */
+    async searchCandidates(query = {}) {
+        const records = await this.searchRecords(query);
+        return records.map((record) => normalizeCatalogAgent(record));
+    }
+    /** 取单个候选（CatalogSource 接口面）。 */
+    async getCandidate(catalogAgentId) {
+        const record = await this.getRecord(catalogAgentId);
+        return normalizeCatalogAgent(record);
+    }
+    /** 搜索 listing（v0.4 §8；rev1.5 CD #22/#24）。分页完整拉取，跨页去重；
+     *  limit 是总返回上限而非页大小（历史教训：--limit N 曾返回全目录）。 */
+    async searchListings(query = {}) {
+        const results = [];
+        const seen = new Set();
+        const limit = query.limit;
+        let cursor;
+        for (let page = 0; page < MAX_SEARCH_PAGES; page++) {
+            // 先构造查询（buildListingSearchQuery 校验 limit 为正整数，fail-closed），
+            // 再判总量封顶——提前 break 会绕过校验（limit=0 必须 reject）。
+            const qs = buildListingSearchQuery({ ...query, ...(cursor !== undefined ? { cursor } : {}) });
+            if (limit !== undefined && results.length >= limit)
+                break;
+            const raw = await this.getJson(`/v1/listings/search${qs.length > 0 ? `?${qs}` : ""}`);
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                throw new CatalogSourceError("response_invalid", "kiwi-catalog listings search response must be a JSON object");
+            }
+            const body = raw;
+            if (!Array.isArray(body.results)) {
+                throw new CatalogSourceError("response_invalid", 'kiwi-catalog listings search response is missing array field "results"');
+            }
+            for (const element of body.results) {
+                if (limit !== undefined && results.length >= limit)
+                    break;
+                const result = validateListingSearchResult(element);
+                if (seen.has(result.listing.listing_id))
+                    continue;
+                seen.add(result.listing.listing_id);
+                results.push(result);
+            }
+            const next = body.next_cursor;
+            if (typeof next !== "string" || next === "")
+                break;
+            cursor = next;
+        }
+        return limit !== undefined ? results.slice(0, limit) : results;
+    }
+    /** 按 listing_id 取单个 listing record（publisher 自查/详情）。 */
+    async getListing(listingId) {
+        if (typeof listingId !== "string" || listingId.length === 0) {
+            throw new CatalogSourceError("invalid_input", "listingId must be a non-empty string");
+        }
+        const raw = await this.getJson(`/v1/listings/${encodeURIComponent(listingId)}`);
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw new CatalogSourceError("response_invalid", "kiwi-catalog get listing response must be an object");
+        }
+        const body = raw;
+        if (body.listing === undefined) {
+            throw new CatalogSourceError("response_invalid", 'kiwi-catalog get listing is missing field "listing"');
+        }
+        return validateListingRecord(body.listing);
+    }
+}
+/**
+ * 序列化 listing 搜索查询。未知键 → invalid_input（fail-closed，不静默丢弃）；
+ * attribute.<path> 过滤键允许（v0.4 §8 attribute filters）。
+ */
+function buildListingSearchQuery(query) {
+    for (const key of Object.keys(query)) {
+        if (!KIWI_LISTING_SEARCH_QUERY_KEYS.includes(key)) {
+            throw new CatalogSourceError("invalid_input", `unknown kiwi-catalog listing search query key: "${key}"`);
+        }
+    }
+    if (query.limit !== undefined && (!Number.isInteger(query.limit) || query.limit <= 0)) {
+        throw new CatalogSourceError("invalid_input", `kiwi-catalog listing search limit must be a positive integer (got ${query.limit})`);
+    }
+    const entries = [];
+    const push = (key, value) => {
+        if (value !== undefined)
+            entries.push([key, String(value)]);
+    };
+    push("q", query.q);
+    push("listing_type", query.listing_type);
+    push("category", query.category);
+    push("brand", query.brand);
+    push("region", query.region);
+    push("tag", query.tag);
+    push("min_moq", query.min_moq);
+    push("max_moq", query.max_moq);
+    push("supports_bulk_quote", query.supports_bulk_quote);
+    push("supports_customization", query.supports_customization);
+    push("freshness_state", query.freshness_state);
+    push("handoff_destination_type", query.handoff_destination_type);
+    if (query.limit !== undefined)
+        push("limit", query.limit);
+    push("cursor", query.cursor);
+    return new URLSearchParams(entries).toString();
+}
+//# sourceMappingURL=kiwi-source.js.map

package/dist/discovery/catalog-source/kiwi-source.js.map

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

package/dist/discovery/catalog-source/register.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.
+ */
+export interface CatalogRegisterInput {
+    /** catalog 服务 base URL（如 http://127.0.0.1:8600）。 */
+    catalogBaseUrl: string;
+    /** 注册域名（必填，catalog 规范化）。 */
+    domain: string;
+    /** merchant 自己的 Agent Card well-known URL。 */
+    agentCardUrl: string;
+    /** merchant 自己的 UCP profile well-known URL（可选）。 */
+    ucpProfileUrl?: string;
+    /** 绑定 merchant_id（owner 语义，可选）。 */
+    merchantId?: string;
+    /**
+     * KIWI_CATALOG_OWNER_TOKEN_SECRET：绑定 merchant_id 时用于派生 owner_token
+     * （HMAC-SHA256("kiwi-catalog-owner:" + merchant_id)）。未提供则按公开
+     * 自助注册（不带 merchant_id）处理。
+     */
+    ownerTokenSecret?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface CatalogRegisterResult {
+    ok: boolean;
+    catalogAgentId?: string;
+    status?: string;
+    verificationEnqueued?: boolean;
+}
+/** 规范化 catalog base URL：去掉尾部斜杠。 */
+export declare function normalizeCatalogBaseUrl(url: string): string;
+/**
+ * 注册一个 agent 到 catalog（fail closed：非 2xx 或 error 信封 → 抛错）。
+ * 幂等：同 domain + agent_card_url 重复注册由 catalog 侧幂等处理，安全可重试。
+ */
+export declare function registerCatalogAgent(input: CatalogRegisterInput): Promise<CatalogRegisterResult>;