@ai-agent-forge/plugin-memory 0.88.0 → 0.88.3

package/dist/memory/embedding-reranker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding-reranker.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC7C,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,MAAM,MAAM,4BAA4B,GAAG,CAC1C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAsC5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,iGAAiG;IACjG,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,gBAAgB,CA+CnB","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow lastError;\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"embedding-reranker.d.ts","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+FAA+F;IAC/F,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;CAC3E;AAED;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC7C,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5D;AAED,MAAM,MAAM,4BAA4B,GAAG,CAC1C,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,6BAA6B,CAAC,CAAC;AAsC5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IACjD,iGAAiG;IACjG,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,gBAAgB,CA0DnB","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { annotateUpstreamListingPoison, purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t\t// 同 host 一次短退避重试 (2026-10-06 live E2E): 覆盖 rejection 型瞬断\n\t\t\t\t// (fetch 网络错/5xx)。对\"仓库 API 清单缺文件\"型不生效——该结果被\n\t\t\t\t// transformers 模块级 memoize (见 annotateUpstreamListingPoison),\n\t\t\t\t// 进程内换 host 也拿同一空清单。\n\t\t\t\ttry {\n\t\t\t\t\tawait new Promise((resolve) => setTimeout(resolve, 2_000));\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow annotateUpstreamListingPoison(lastError);\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/embedding-reranker.js

@@ -24,7 +24,7 @@
  */
 import { join } from "node:path";
 import { importHostOrBareModule } from "./host-module-import.js";
-import { purgeZeroByteCacheArtifacts } from "./model-cache-hygiene.js";
+import { annotateUpstreamListingPoison, purgeZeroByteCacheArtifacts } from "./model-cache-hygiene.js";
 const DEFAULT_RERANKER_MODEL_ID = "Xenova/bge-reranker-base";
 const DEFAULT_REMOTE_HOST = "https://huggingface.co";
 const createDefaultTransformersLoadImpl = (moduleEntryPath) => {
@@ -80,10 +80,22 @@ export function createTransformersReranker(options) {
                     // 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。
                     purgeZeroByteCacheArtifacts(join(cacheDir, modelId));
                 }
+                // 同 host 一次短退避重试 (2026-10-06 live E2E): 覆盖 rejection 型瞬断
+                // (fetch 网络错/5xx)。对"仓库 API 清单缺文件"型不生效——该结果被
+                // transformers 模块级 memoize (见 annotateUpstreamListingPoison),
+                // 进程内换 host 也拿同一空清单。
+                try {
+                    await new Promise((resolve) => setTimeout(resolve, 2_000));
+                    return await load(modelId, cacheDir, remoteHost);
+                }
+                catch (error) {
+                    lastError = error;
+                    purgeZeroByteCacheArtifacts(join(cacheDir, modelId));
+                }
             }
             if (lastError === undefined)
                 throw new Error(`no remote hosts configured for model ${modelId}`);
-            throw lastError;
+            throw annotateUpstreamListingPoison(lastError);
         })();
         backendPromise = attempt;
         attempt.catch(() => {

package/dist/memory/embedding-reranker.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedding-reranker.js","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow lastError;\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}
+{"version":3,"file":"embedding-reranker.js","sourceRoot":"","sources":["../../src/memory/embedding-reranker.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Memory cross-encoder reranker for hybrid retrieval (混合检索 · 精排侧).\n *\n * POC-verified (2026-09, 100k corpus): reranking drift-query retrieval with\n * Xenova/bge-reranker-base lifts high-tier recall to re@10 100% (低档 83%),\n * inference deterministic across runs. Reranking is an independently\n * disable-able component (宪法: 独立可禁用); tiers are caller configuration.\n *\n * Model note: default \"Xenova/bge-reranker-base\" is the only officially\n * converted (transformers.js) reranker verified in POC; q8 weights ~280MB,\n * 512-token context — the caller owns the write-side length contract\n * (statement ≤700 chars); overlong inputs are gracefully truncated by the\n * tokenizer (`truncation: true`). Upgrade path bge-reranker-v2-m3 is a\n * modelId swap away, but it currently has no official transformers.js\n * conversion.\n *\n * Runtime dep @huggingface/transformers is lazy-loaded via `await import` at\n * first rerank (惯例参考 packages/agent-forge/src/utils/photon.ts); type\n * positions use type-only imports. Any failure propagates — 不静默降级.\n */\n\n/**\n * Cross-encoder reranker. Higher score = more relevant; raw logits are only\n * order-preserving, not calibrated probabilities.\n */\nimport { join } from \"node:path\";\nimport { importHostOrBareModule } from \"./host-module-import.ts\";\nimport { annotateUpstreamListingPoison, purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\nexport interface MemoryRerankerV1 {\n\treadonly modelId: string;\n\t/** Score each doc against the query; higher = more relevant (raw logits, order-preserving). */\n\trerank(query: string, docs: readonly string[]): Promise<readonly number[]>;\n}\n\n/**\n * Minimal structural seam around a transformers.js sequence-classification\n * pair, so tests can inject a fake without touching the real loader.\n */\nexport interface TransformersRerankerBackendV1 {\n\t/** Score docs against the query; result[i] corresponds to docs[i]. */\n\tscore: (query: string, docs: string[]) => Promise<number[]>;\n}\n\nexport type TransformersRerankerLoadImpl = (\n\tmodelId: string,\n\tcacheDir: string,\n\tremoteHost: string,\n) => Promise<TransformersRerankerBackendV1>;\n\nconst DEFAULT_RERANKER_MODEL_ID = \"Xenova/bge-reranker-base\";\nconst DEFAULT_REMOTE_HOST = \"https://huggingface.co\";\n\n/** Structural view of the tokenizer call; returns the model-input object. */\ntype RerankTokenizerCall = (\n\ttexts: string[],\n\toptions: { text_pair: string[]; padding: boolean; truncation: boolean },\n) => unknown;\n\n/** Structural view of the sequence-classification forward pass. */\ntype RerankModelCall = (inputs: unknown) => Promise<{ logits: { data: ArrayLike<number> } }>;\n\nconst createDefaultTransformersLoadImpl = (moduleEntryPath?: string): TransformersRerankerLoadImpl => {\n\treturn async (modelId, cacheDir, remoteHost) => {\n\t\tconst transformers = await importHostOrBareModule<typeof import(\"@huggingface/transformers\")>(\n\t\t\tmoduleEntryPath ?? \"@huggingface/transformers\",\n\t\t);\n\t\ttransformers.env.cacheDir = cacheDir;\n\t\ttransformers.env.remoteHost = remoteHost;\n\t\tconst tokenizer = (await transformers.AutoTokenizer.from_pretrained(modelId)) as unknown as RerankTokenizerCall;\n\t\tconst model = (await transformers.AutoModelForSequenceClassification.from_pretrained(modelId, {\n\t\t\tdtype: \"q8\",\n\t\t})) as unknown as RerankModelCall;\n\t\treturn {\n\t\t\tscore: async (query, docs) => {\n\t\t\t\tconst inputs = tokenizer(\n\t\t\t\t\tdocs.map(() => query),\n\t\t\t\t\t{ text_pair: docs, padding: true, truncation: true },\n\t\t\t\t);\n\t\t\t\tconst output = await model(inputs);\n\t\t\t\treturn Array.from(output.logits.data);\n\t\t\t},\n\t\t};\n\t};\n};\n\n/**\n * Transformers.js-backed cross-encoder reranker (两档共用默认\n * Xenova/bge-reranker-base, 见文件头模型说明)。\n *\n * 镜像序列: 首次 rerank 时按 `remoteHosts` 顺序逐个尝试加载 (调用方通常传\n * [\"https://huggingface.co\", \"https://hf-mirror.com\"]); 某 host 加载抛错则\n * 尝试下一个, 全部失败时抛最后一个错误。host 确定后模型句柄只加载一次\n * (并发 rerank 共享同一 in-flight promise); 加载失败不缓存, 下次 rerank\n * 重新走完整序列, 失败原因原样保留, 不静默降级。\n *\n * `loadImpl` 是测试 seam: 注入后绕过真实加载, 签名\n * (modelId, cacheDir, remoteHost) => backend。\n */\nexport function createTransformersReranker(options: {\n\treadonly modelId?: string;\n\treadonly cacheDir: string;\n\treadonly remoteHosts?: readonly string[];\n\treadonly loadImpl?: TransformersRerankerLoadImpl;\n\t/** Host-resolved transformers entry path (install-store visibility); undefined = bare import. */\n\treadonly moduleEntryPath?: string;\n}): MemoryRerankerV1 {\n\tconst modelId = options.modelId ?? DEFAULT_RERANKER_MODEL_ID;\n\tconst cacheDir = options.cacheDir;\n\tconst remoteHosts = options.remoteHosts ?? [DEFAULT_REMOTE_HOST];\n\tconst load = options.loadImpl ?? createDefaultTransformersLoadImpl(options.moduleEntryPath);\n\n\tlet backendPromise: Promise<TransformersRerankerBackendV1> | null = null;\n\tconst loadBackend = (): Promise<TransformersRerankerBackendV1> => {\n\t\tconst existing = backendPromise;\n\t\tif (existing) {\n\t\t\treturn existing;\n\t\t}\n\t\tconst attempt = (async () => {\n\t\t\tlet lastError: unknown;\n\t\t\tfor (const remoteHost of remoteHosts) {\n\t\t\t\ttry {\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\t// 镜像轮换前清 0 字节残骸 (embedding-provider 同理, model-cache-hygiene)。\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t\t// 同 host 一次短退避重试 (2026-10-06 live E2E): 覆盖 rejection 型瞬断\n\t\t\t\t// (fetch 网络错/5xx)。对\"仓库 API 清单缺文件\"型不生效——该结果被\n\t\t\t\t// transformers 模块级 memoize (见 annotateUpstreamListingPoison),\n\t\t\t\t// 进程内换 host 也拿同一空清单。\n\t\t\t\ttry {\n\t\t\t\t\tawait new Promise((resolve) => setTimeout(resolve, 2_000));\n\t\t\t\t\treturn await load(modelId, cacheDir, remoteHost);\n\t\t\t\t} catch (error) {\n\t\t\t\t\tlastError = error;\n\t\t\t\t\tpurgeZeroByteCacheArtifacts(join(cacheDir, modelId));\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (lastError === undefined) throw new Error(`no remote hosts configured for model ${modelId}`);\n\t\t\tthrow annotateUpstreamListingPoison(lastError);\n\t\t})();\n\t\tbackendPromise = attempt;\n\t\tattempt.catch(() => {\n\t\t\t// 失败不缓存: 下次 rerank 重新走镜像序列 (显式失败, 不静默降级)。\n\t\t\tif (backendPromise === attempt) {\n\t\t\t\tbackendPromise = null;\n\t\t\t}\n\t\t});\n\t\treturn attempt;\n\t};\n\n\treturn {\n\t\tmodelId,\n\t\trerank: async (query, docs) => {\n\t\t\tif (docs.length === 0) {\n\t\t\t\t// 空 docs 直接返回, 不触发模型加载 (lazy-load 只发生在真正需要打分时)。\n\t\t\t\treturn [];\n\t\t\t}\n\t\t\tconst backend = await loadBackend();\n\t\t\treturn backend.score(query, [...docs]);\n\t\t},\n\t};\n}\n"]}

package/dist/memory/enabling.d.ts

@@ -0,0 +1,104 @@
+/**
+ * enabling 前置检查、档位预设与镜像源（capability 拆分战役 slice 1）：纯函数,
+ * 无闭包依赖。
+ */
+import type { MemoryModeV1 } from "@agent-forge/plugin-sdk";
+/** 开启前磁盘余量下限 (设计 §3.2 checking): light ≥ 500MB, full ≥ 2GB。 */
+export declare const DISK_HEADROOM_MIN_BYTES: Readonly<Record<Exclude<MemoryModeV1, "off">, number>>;
+/**
+ * 模型文件大小下限 (防截断/空文件的 sanity 下限, 非精确体积): 高档 embedding
+ * (bge-m3 q8) 数百 MB → 下限 256MB, 精排器 (bge-reranker-base q8) ~280MB →
+ * 下限 64MB, 低档 (bge-small-zh q8) ~24MB → 下限 8MB。真实校验由加载冒烟承担。
+ */
+export declare const MODEL_MIN_WEIGHT_BYTES: Readonly<Record<Exclude<MemoryModeV1, "off">, number>>;
+export declare const RERANKER_MIN_WEIGHT_BYTES: number;
+/** 两档预设 (实施计划 §2): light = 纯中文强项低配档, full = 跨语言大规模默认档。 */
+interface MemoryVectorPresetV1 {
+    readonly embeddingModelId: string;
+    readonly dimensions: number;
+    /** 查询侧指令前缀 (bge-small-zh 系查询侧指令由调用方负责添加; 写入侧不加)。 */
+    readonly queryPrefix: string;
+}
+export declare const VECTOR_PRESET_LIGHT: MemoryVectorPresetV1;
+export declare const VECTOR_PRESET_FULL: MemoryVectorPresetV1;
+/** 档位预设: mode → 模型组合。off 在进入装配前已被门控拦截。 */
+export declare function vectorPresetForMode(mode: Exclude<MemoryModeV1, "off">): MemoryVectorPresetV1;
+/**
+ * agentDir 身份归一化 (2026-10-06 串线修复): 绝对路径解析抹平分隔符与相对段,
+ * win32 再 casefold —— 同一目录在 Windows 下的大小写差异 (盘符/路径段) 不得
+ * 误判为跨 agent-dir 串线。仅用于身份比对, 不触碰文件系统语义。
+ */
+export declare function normalizeMemoryAgentDirIdentity(agentDir: string): string;
+/**
+ * 自定义镜像源 (失败行动清单第一项指向它): env `AGENT_FORGE_HF_MIRRORS` 逗号
+ * 分隔 host 列表, 排在默认镜像序列之前优先尝试; 默认序列直连 huggingface.co
+ * 超时时回落 hf-mirror.com。
+ *
+ * env 条目归一化 (2026-10-06 live E2E 修复): 裸主机名补 `https://` — 用户
+ * 按行动清单写 `AGENT_FORGE_HF_MIRRORS=hf-mirror.com` 时, 无 scheme 的
+ * remoteHost 会让 transformers 的文件请求按相对 URL 解析并在模块内留下
+ * 毒化状态, 连后续带 scheme 的镜像重试也崩; 行动清单推荐的自救手段本身
+ * 不能是断的。已带 scheme 的条目原样保留, 尾部 `/` 去除。
+ */
+export declare function remoteHostsForEnabling(): readonly string[];
+export declare function nativeBinaryCheck(hostEntryPath?: string): string | undefined;
+/**
+ * 重依赖自解析默认实现 (missingHeavyDependencyModules 生产接线): 双通道与
+ * {@link resolveOnnxRuntimeEntryPath} 一致 — jiti（安装店加载缝）注入的
+ * `require` 走宿主 alias 表; 纯 ESM（源码/工作区直载）下回落原生 createRequire。
+ */
+export declare function resolveHeavyDependencyEntryPath(specifier: string): string;
+/**
+ * 本地检查 1b: 重依赖供给 (设计 §3.2 checking)。`@lancedb/lancedb` 与
+ * `@huggingface/transformers` 逐个判定 — entries 提供宿主入口路径 = 可用
+ * (不触自解析); 未提供时 resolveModule 自解析成功 = 可用, 抛错 = 计入缺失。
+ * 返回缺失 specifier 列表 (空 = 通过)。纯函数零 IO; 导出仅供测试 (与宿主侧
+ * buildHostDependencyAliases 同一模式), 生产接线传插件位置自解析 — 把加载步
+ * 的 "Cannot find module" 泛化包装前置成精准缺供文案, 省掉模型下载等前置工作。
+ */
+export declare function missingHeavyDependencyModules(entries: {
+    lancedb?: string;
+    transformers?: string;
+}, resolveModule: (specifier: string) => string): string[];
+/**
+ * transformers.js 缓存布局的容错存在性检查 (设计 §3.2 手动导入路径):
+ * `<cacheDir>/<modelId>/` 下需有非空 tokenizer 文件与 `onnx/` 权重文件。
+ * 返回 undefined = 检查通过; "missing" = 目录/文件缺失或仅剩 0 字节残骸
+ * (失败下载产物, 清理后进入下载阶段, 见 model-cache-hygiene); 其他字符串 =
+ * 文件存在但可疑 (截断/非空过小), 属失败。
+ */
+export declare function modelFilesCheck(cacheDir: string, modelId: string, minWeightBytes: number): string | undefined;
+/**
+ * 本地检查 3: 磁盘余量 (设计 §3.2 checking, node:fs statfs, 零新依赖)。
+ * 以 agentDir 所在卷为准 (cacheDir 同卷创建)。agentDir 可能尚不存在 (全新
+ * 机器首启, 下载前无人创建过它 — 2026-10-06 live E2E 实测踩中) — statfs
+ * ENOENT 时逐级上溯最近存在的祖先目录, 同卷即同余量; 上溯到根仍失败才按
+ * 无法判定报告。
+ */
+export declare function diskHeadroomCheck(agentDir: string, minimumBytes: number): Promise<string | undefined>;
+/** enabling 失败的五选一行动清单 (设计 §3.2 硬性要求)。 */
+export declare function enablingActionList(modelCacheDir: string, currentMode: MemoryModeV1): readonly string[];
+/** agent-dir 配置文件里的征询拒绝标记值 (memoryConsent 键)。 */
+export declare const MEMORY_CONSENT_DECLINED_VALUE = "declined";
+/** memory 插件 agent-dir 配置通道 (entry 读、capability 写, 同一路径)。 */
+export declare const MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH: string;
+/** agent-dir 配置里用户显式持久化的档位键 (无 / 该键即 undefined)。 */
+export declare function readMemorySettingsMode(agentDir: string): "light" | "full" | undefined;
+/**
+ * 拒绝/跳过的持久化 (2026-10-05 用户裁决): 写入插件自己的 agent-dir 配置文件,
+ * 不改写用户 settings.json。语义是「用户对默认档说了不」——仅抑制默认档;
+ * 用户日后显式设置 settings.json `memory.mode` (light/full) 时显式值仍然生效。
+ * 同时移除 /memory light|full 持久化的档位键, 保证"先升 full 再 off"不会留下
+ * 一个压过 settings 的陈旧档位。
+ */
+export declare function writeMemoryConsentDeclined(agentDir: string): void;
+/**
+ * 档位升级/降级的持久化 (/memory light|full): 写入插件 agent-dir 配置的
+ * `memorySettingsMode` 键——与 settings.json `memory.mode` 同一解析层 (持久
+ * 配置面, env 仍可临时覆盖)。插件无 settings.json 写通道 (HostCapabilities
+ * 无该面), 本文件键在其上, 即命令是比 settings 更近一次的显式表达。同时清
+ * 除拒绝标记: 显式升/降档是最新的用户意图, 压过此前的"对默认档说不"。
+ */
+export declare function writeMemorySettingsMode(agentDir: string, mode: "light" | "full"): void;
+export {};
+//# sourceMappingURL=enabling.d.ts.map

package/dist/memory/enabling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enabling.d.ts","sourceRoot":"","sources":["../../src/memory/enabling.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D,4FAA+D;AAC/D,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAG1F,CAAC;AACF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CAGzF,CAAC;AACF,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAI1D,+GAA0D;AAC1D,UAAU,oBAAoB;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0GAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,mBAAmB,EAAE,oBAIjC,CAAC;AACF,eAAO,MAAM,kBAAkB,EAAE,oBAIhC,CAAC;AAIF,wFAA0C;AAC1C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC,GAAG,oBAAoB,CAE5F;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,MAAM,EAAE,CAO1D;AAsBD,wBAAgB,iBAAiB,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkC5E;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CASzE;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,CAC5C,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,EACpD,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GAC1C,MAAM,EAAE,CAeV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB7G;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAyB3G;AAED,6EAA0C;AAC1C,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,GAAG,SAAS,MAAM,EAAE,CAUtG;AAQD,+EAAiD;AACjD,eAAO,MAAM,6BAA6B,aAAa,CAAC;AACxD,yFAA6D;AAC7D,eAAO,MAAM,qCAAqC,QAA8C,CAAC;AAgCjG,0FAAoD;AACpD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAGrF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAMjE;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAKtF","sourcesContent":["/**\n * enabling 前置检查、档位预设与镜像源（capability 拆分战役 slice 1）：纯函数,\n * 无闭包依赖。\n */\n\nimport { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from \"node:fs\";\nimport { statfs } from \"node:fs/promises\";\nimport { createRequire } from \"node:module\";\nimport { dirname, join, resolve } from \"node:path\";\nimport type { MemoryModeV1 } from \"@agent-forge/plugin-sdk\";\nimport { purgeZeroByteCacheArtifacts } from \"./model-cache-hygiene.ts\";\n\n/** 开启前磁盘余量下限 (设计 §3.2 checking): light ≥ 500MB, full ≥ 2GB。 */\nexport const DISK_HEADROOM_MIN_BYTES: Readonly<Record<Exclude<MemoryModeV1, \"off\">, number>> = {\n\tlight: 500 * 1024 * 1024,\n\tfull: 2 * 1024 * 1024 * 1024,\n};\n/**\n * 模型文件大小下限 (防截断/空文件的 sanity 下限, 非精确体积): 高档 embedding\n * (bge-m3 q8) 数百 MB → 下限 256MB, 精排器 (bge-reranker-base q8) ~280MB →\n * 下限 64MB, 低档 (bge-small-zh q8) ~24MB → 下限 8MB。真实校验由加载冒烟承担。\n */\nexport const MODEL_MIN_WEIGHT_BYTES: Readonly<Record<Exclude<MemoryModeV1, \"off\">, number>> = {\n\tlight: 8 * 1024 * 1024,\n\tfull: 256 * 1024 * 1024,\n};\nexport const RERANKER_MIN_WEIGHT_BYTES = 64 * 1024 * 1024;\n/** 自定义镜像源环境变量 (失败行动清单第一项指向它)。 */\nconst HF_MIRRORS_ENV = \"AGENT_FORGE_HF_MIRRORS\";\n\n/** 两档预设 (实施计划 §2): light = 纯中文强项低配档, full = 跨语言大规模默认档。 */\ninterface MemoryVectorPresetV1 {\n\treadonly embeddingModelId: string;\n\treadonly dimensions: number;\n\t/** 查询侧指令前缀 (bge-small-zh 系查询侧指令由调用方负责添加; 写入侧不加)。 */\n\treadonly queryPrefix: string;\n}\n\nexport const VECTOR_PRESET_LIGHT: MemoryVectorPresetV1 = {\n\tembeddingModelId: \"Xenova/bge-small-zh-v1.5\",\n\tdimensions: 512,\n\tqueryPrefix: \"为这个句子生成表示以用于检索相关文章：\",\n};\nexport const VECTOR_PRESET_FULL: MemoryVectorPresetV1 = {\n\tembeddingModelId: \"Xenova/bge-m3\",\n\tdimensions: 1024,\n\tqueryPrefix: \"\",\n};\n/** 镜像序列 (实施计划 §7): 直连 huggingface.co 超时时回落 hf-mirror.com。 */\nconst VECTOR_REMOTE_HOSTS: readonly string[] = [\"https://huggingface.co\", \"https://hf-mirror.com\"];\n\n/** 档位预设: mode → 模型组合。off 在进入装配前已被门控拦截。 */\nexport function vectorPresetForMode(mode: Exclude<MemoryModeV1, \"off\">): MemoryVectorPresetV1 {\n\treturn mode === \"light\" ? VECTOR_PRESET_LIGHT : VECTOR_PRESET_FULL;\n}\n\n/**\n * agentDir 身份归一化 (2026-10-06 串线修复): 绝对路径解析抹平分隔符与相对段,\n * win32 再 casefold —— 同一目录在 Windows 下的大小写差异 (盘符/路径段) 不得\n * 误判为跨 agent-dir 串线。仅用于身份比对, 不触碰文件系统语义。\n */\nexport function normalizeMemoryAgentDirIdentity(agentDir: string): string {\n\tconst resolvedPath = resolve(agentDir);\n\treturn process.platform === \"win32\" ? resolvedPath.toLowerCase() : resolvedPath;\n}\n\n/**\n * 自定义镜像源 (失败行动清单第一项指向它): env `AGENT_FORGE_HF_MIRRORS` 逗号\n * 分隔 host 列表, 排在默认镜像序列之前优先尝试; 默认序列直连 huggingface.co\n * 超时时回落 hf-mirror.com。\n *\n * env 条目归一化 (2026-10-06 live E2E 修复): 裸主机名补 `https://` — 用户\n * 按行动清单写 `AGENT_FORGE_HF_MIRRORS=hf-mirror.com` 时, 无 scheme 的\n * remoteHost 会让 transformers 的文件请求按相对 URL 解析并在模块内留下\n * 毒化状态, 连后续带 scheme 的镜像重试也崩; 行动清单推荐的自救手段本身\n * 不能是断的。已带 scheme 的条目原样保留, 尾部 `/` 去除。\n */\nexport function remoteHostsForEnabling(): readonly string[] {\n\tconst custom = process.env[HF_MIRRORS_ENV]\n\t\t?.split(\",\")\n\t\t.map((host) => host.trim().replace(/\\/+$/, \"\"))\n\t\t.map((host) => (host === \"\" || host.includes(\"://\") ? host : `https://${host}`))\n\t\t.filter((host) => host !== \"\");\n\treturn custom === undefined || custom.length === 0 ? VECTOR_REMOTE_HOSTS : [...custom, ...VECTOR_REMOTE_HOSTS];\n}\n\n/**\n * 本地检查 1: native .node sidecar 可解析 (设计 §3.2 checking)。布局:\n * onnxruntime-node/bin 下的 napi-vN/<platform>/<arch> 原生模块 — 缺失 = 安装\n * 损坏。容错: 不钉死 napi 版本号, 逐目录扫描。\n *\n * 解析基点双通道: jiti（安装店加载缝）注入的 `require` 走宿主 alias 表\n * （宿主 node_modules 副本, 店内无依赖树）; 纯 ESM（源码/工作区直载）下裸\n * `require` 未定义（typeof 探测不抛 ReferenceError）, 回落原生 createRequire。\n */\nfunction resolveOnnxRuntimeEntryPath(): string {\n\tif (typeof require === \"function\") {\n\t\ttry {\n\t\t\treturn require.resolve(\"onnxruntime-node\");\n\t\t} catch {\n\t\t\t// jiti 解析失败（alias 未覆盖等）→ 继续走原生解析再报结构化错误。\n\t\t}\n\t}\n\treturn createRequire(import.meta.url).resolve(\"onnxruntime-node\");\n}\n\nexport function nativeBinaryCheck(hostEntryPath?: string): string | undefined {\n\t// 两种失败要区分 (D-075 安装店路径修复后前者成为真实可达路径):\n\t// (a) 宿主未注入入口路径且插件位置自解析不到 — 不是安装损坏, 行动是宿主侧\n\t//     安装重依赖后重启会话, 不是重装插件;\n\t// (b) 路径存在但原生二进制缺失/损坏 — 保留损坏类文案。\n\tlet entryPath: string;\n\tif (hostEntryPath === undefined) {\n\t\ttry {\n\t\t\tentryPath = resolveOnnxRuntimeEntryPath();\n\t\t} catch (error) {\n\t\t\tconst detail = error instanceof Error ? error.message : String(error);\n\t\t\treturn `onnxruntime-node is not provided by the host installation and could not be resolved from the plugin location (${detail}); to enable memory features, install onnxruntime-node in the host project (npm i onnxruntime-node) and restart the session`;\n\t\t}\n\t} else {\n\t\tentryPath = hostEntryPath;\n\t}\n\ttry {\n\t\tlet packageDir = dirname(entryPath);\n\t\twhile (packageDir !== dirname(packageDir) && !existsSync(join(packageDir, \"package.json\"))) {\n\t\t\tpackageDir = dirname(packageDir);\n\t\t}\n\t\tconst binDir = join(packageDir, \"bin\");\n\t\tif (!existsSync(binDir)) return `onnxruntime native binary directory not found: ${binDir}`;\n\t\tfor (const napiEntry of readdirSync(binDir, { withFileTypes: true })) {\n\t\t\tif (!napiEntry.isDirectory() || !napiEntry.name.startsWith(\"napi-v\")) continue;\n\t\t\tconst platformDir = join(binDir, napiEntry.name, process.platform, process.arch);\n\t\t\tif (!existsSync(platformDir)) continue;\n\t\t\tconst binaries = readdirSync(platformDir).filter((file) => file.endsWith(\".node\"));\n\t\t\tif (binaries.length > 0) return undefined;\n\t\t}\n\t\treturn `onnxruntime native binary for ${process.platform}/${process.arch} not found under ${binDir}`;\n\t} catch (error) {\n\t\treturn `onnxruntime native binary could not be resolved (${error instanceof Error ? error.message : String(error)}); the installation looks damaged — reinstall the package`;\n\t}\n}\n\n/**\n * 重依赖自解析默认实现 (missingHeavyDependencyModules 生产接线): 双通道与\n * {@link resolveOnnxRuntimeEntryPath} 一致 — jiti（安装店加载缝）注入的\n * `require` 走宿主 alias 表; 纯 ESM（源码/工作区直载）下回落原生 createRequire。\n */\nexport function resolveHeavyDependencyEntryPath(specifier: string): string {\n\tif (typeof require === \"function\") {\n\t\ttry {\n\t\t\treturn require.resolve(specifier);\n\t\t} catch {\n\t\t\t// jiti 解析失败（alias 未覆盖等）→ 继续走原生解析。\n\t\t}\n\t}\n\treturn createRequire(import.meta.url).resolve(specifier);\n}\n\n/**\n * 本地检查 1b: 重依赖供给 (设计 §3.2 checking)。`@lancedb/lancedb` 与\n * `@huggingface/transformers` 逐个判定 — entries 提供宿主入口路径 = 可用\n * (不触自解析); 未提供时 resolveModule 自解析成功 = 可用, 抛错 = 计入缺失。\n * 返回缺失 specifier 列表 (空 = 通过)。纯函数零 IO; 导出仅供测试 (与宿主侧\n * buildHostDependencyAliases 同一模式), 生产接线传插件位置自解析 — 把加载步\n * 的 \"Cannot find module\" 泛化包装前置成精准缺供文案, 省掉模型下载等前置工作。\n */\nexport function missingHeavyDependencyModules(\n\tentries: { lancedb?: string; transformers?: string },\n\tresolveModule: (specifier: string) => string,\n): string[] {\n\tconst missing: string[] = [];\n\tconst supplies: readonly (readonly [specifier: string, entryPath: string | undefined])[] = [\n\t\t[\"@lancedb/lancedb\", entries.lancedb],\n\t\t[\"@huggingface/transformers\", entries.transformers],\n\t];\n\tfor (const [specifier, entryPath] of supplies) {\n\t\tif (entryPath !== undefined) continue;\n\t\ttry {\n\t\t\tresolveModule(specifier);\n\t\t} catch {\n\t\t\tmissing.push(specifier);\n\t\t}\n\t}\n\treturn missing;\n}\n\n/**\n * transformers.js 缓存布局的容错存在性检查 (设计 §3.2 手动导入路径):\n * `<cacheDir>/<modelId>/` 下需有非空 tokenizer 文件与 `onnx/` 权重文件。\n * 返回 undefined = 检查通过; \"missing\" = 目录/文件缺失或仅剩 0 字节残骸\n * (失败下载产物, 清理后进入下载阶段, 见 model-cache-hygiene); 其他字符串 =\n * 文件存在但可疑 (截断/非空过小), 属失败。\n */\nexport function modelFilesCheck(cacheDir: string, modelId: string, minWeightBytes: number): string | undefined {\n\tconst modelDir = join(cacheDir, modelId);\n\tif (!existsSync(modelDir)) return \"missing\";\n\t// tokenizer 只剩 0 字节文件 = 失败下载残骸 (真 tokenizer.json 不可能为空):\n\t// 清掉按缺失处理可重下; 非空文件不动 (手动导入布局不受影响)。\n\tconst tokenizerNames = [\"tokenizer.json\", \"tokenizer.model\"].filter((name) => existsSync(join(modelDir, name)));\n\tconst hasTokenizer = tokenizerNames.some((name) => statSync(join(modelDir, name)).size > 0);\n\tif (!hasTokenizer) {\n\t\tif (tokenizerNames.length > 0) purgeZeroByteCacheArtifacts(modelDir);\n\t\treturn \"missing\";\n\t}\n\tconst onnxDir = join(modelDir, \"onnx\");\n\tif (!existsSync(onnxDir)) return `onnx weight directory missing under ${modelDir}`;\n\tconst weights = readdirSync(onnxDir).filter((name) => name.includes(\".onnx\"));\n\tif (weights.length === 0) return `no onnx weight file under ${onnxDir}`;\n\tconst largest = Math.max(...weights.map((name) => statSync(join(onnxDir, name)).size));\n\tif (largest < minWeightBytes) {\n\t\treturn `largest onnx weight under ${onnxDir} is ${largest} bytes, below the expected minimum ${minWeightBytes} — the download looks truncated`;\n\t}\n\treturn undefined;\n}\n\n/**\n * 本地检查 3: 磁盘余量 (设计 §3.2 checking, node:fs statfs, 零新依赖)。\n * 以 agentDir 所在卷为准 (cacheDir 同卷创建)。agentDir 可能尚不存在 (全新\n * 机器首启, 下载前无人创建过它 — 2026-10-06 live E2E 实测踩中) — statfs\n * ENOENT 时逐级上溯最近存在的祖先目录, 同卷即同余量; 上溯到根仍失败才按\n * 无法判定报告。\n */\nexport async function diskHeadroomCheck(agentDir: string, minimumBytes: number): Promise<string | undefined> {\n\tlet freeBytes: number | undefined;\n\tlet probe: string | undefined = agentDir;\n\tfor (let attempt = 0; probe !== undefined && attempt < 16; attempt++) {\n\t\ttry {\n\t\t\tconst stats = await statfs(probe);\n\t\t\tfreeBytes = stats.bfree * stats.bsize;\n\t\t\tbreak;\n\t\t} catch (error) {\n\t\t\tif (!(error instanceof Error) || !String(error.message).includes(\"ENOENT\")) {\n\t\t\t\treturn `disk free space could not be determined for ${agentDir} (probing ${probe}: ${\n\t\t\t\t\terror instanceof Error ? error.message : String(error)\n\t\t\t\t})`;\n\t\t\t}\n\t\t\tconst parent = dirname(probe);\n\t\t\tprobe = parent === probe ? undefined : parent;\n\t\t}\n\t}\n\tif (freeBytes === undefined) {\n\t\treturn `disk free space could not be determined for ${agentDir} (no existing ancestor directory to statfs)`;\n\t}\n\tif (freeBytes < minimumBytes) {\n\t\treturn `disk free space is ${freeBytes} bytes, below the required ${minimumBytes}`;\n\t}\n\treturn undefined;\n}\n\n/** enabling 失败的五选一行动清单 (设计 §3.2 硬性要求)。 */\nexport function enablingActionList(modelCacheDir: string, currentMode: MemoryModeV1): readonly string[] {\n\treturn [\n\t\t`Switch to a reachable mirror: set ${HF_MIRRORS_ENV} to a comma-separated host list (tried before the defaults)`,\n\t\t`Install the heavy dependencies in the host project (npm i onnxruntime-node @lancedb/lancedb @huggingface/transformers) so the host can supply them via hostDependencyPaths, then restart the session`,\n\t\t`Download the models manually and place them under ${modelCacheDir} (layout: <modelId>/tokenizer.json + <modelId>/onnx/model*.onnx)`,\n\t\tcurrentMode === \"full\"\n\t\t\t? 'Downgrade to memory.mode \"light\" (much smaller models)'\n\t\t\t: 'Keep memory.mode \"light\" and retry with a reachable mirror',\n\t\t'Give up: leave memory.mode \"off\" (the default) so the memory family stays unregistered',\n\t];\n}\n\n// ---------------------------------------------------------------------------\n// 征询持久化 (capability 拆分战役 slice 3b 随迁, 征询域): agent-dir 配置文件\n// 的读写与征询拒绝/档位落盘。纯函数, 路径域显式传入; capability.ts 经\n// re-export 维持历史导出面, 向量通道 (vector-channel.ts) 直接 import。\n// ---------------------------------------------------------------------------\n\n/** agent-dir 配置文件里的征询拒绝标记值 (memoryConsent 键)。 */\nexport const MEMORY_CONSENT_DECLINED_VALUE = \"declined\";\n/** memory 插件 agent-dir 配置通道 (entry 读、capability 写, 同一路径)。 */\nexport const MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH = join(\"capabilities\", \"builtin.memory.json\");\n\nfunction readMemoryAgentDirConfig(agentDir: string): Record<string, unknown> {\n\tconst configPath = join(agentDir, MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH);\n\tif (existsSync(configPath)) {\n\t\ttry {\n\t\t\tconst parsed: unknown = JSON.parse(readFileSync(configPath, \"utf8\"));\n\t\t\tif (parsed !== null && typeof parsed === \"object\" && !Array.isArray(parsed)) {\n\t\t\t\treturn parsed as Record<string, unknown>;\n\t\t\t}\n\t\t} catch {\n\t\t\t// 既有文件非法时以本次写入为准 (持久化是显式用户动作, 不被脏文件阻塞)。\n\t\t}\n\t}\n\treturn {};\n}\n\n/**\n * 写 agent-dir 配置的原子替换 (2026-10-06 复审 P1-2): temp 文件 + rename —\n * 自动升档引入了无人值守写者, 与其它进程的 /memory off (会删档位键) 读改写\n * 交错时, 直接 writeFileSync 可能留下半截 JSON 让并发读者拿到空配置 (整块\n * 丢键: 抹掉并发 decline 或升档)。rename 在同一目录内原子替换, 读者要么见\n * 旧文件要么见新文件。\n */\nfunction writeMemoryAgentDirConfig(agentDir: string, config: Record<string, unknown>): void {\n\tconst configPath = join(agentDir, MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH);\n\tmkdirSync(dirname(configPath), { recursive: true });\n\tconst tempPath = `${configPath}.${process.pid}.tmp`;\n\twriteFileSync(tempPath, `${JSON.stringify(config, null, \"\\t\")}\\n`, \"utf8\");\n\trenameSync(tempPath, configPath);\n}\n\n/** agent-dir 配置里用户显式持久化的档位键 (无 / 该键即 undefined)。 */\nexport function readMemorySettingsMode(agentDir: string): \"light\" | \"full\" | undefined {\n\tconst value = readMemoryAgentDirConfig(agentDir).memorySettingsMode;\n\treturn value === \"light\" || value === \"full\" ? value : undefined;\n}\n\n/**\n * 拒绝/跳过的持久化 (2026-10-05 用户裁决): 写入插件自己的 agent-dir 配置文件,\n * 不改写用户 settings.json。语义是「用户对默认档说了不」——仅抑制默认档;\n * 用户日后显式设置 settings.json `memory.mode` (light/full) 时显式值仍然生效。\n * 同时移除 /memory light|full 持久化的档位键, 保证\"先升 full 再 off\"不会留下\n * 一个压过 settings 的陈旧档位。\n */\nexport function writeMemoryConsentDeclined(agentDir: string): void {\n\tconst config = readMemoryAgentDirConfig(agentDir);\n\tconfig.memoryConsent = MEMORY_CONSENT_DECLINED_VALUE;\n\tdelete config.memorySettingsMode;\n\tdelete config.memoryMode;\n\twriteMemoryAgentDirConfig(agentDir, config);\n}\n\n/**\n * 档位升级/降级的持久化 (/memory light|full): 写入插件 agent-dir 配置的\n * `memorySettingsMode` 键——与 settings.json `memory.mode` 同一解析层 (持久\n * 配置面, env 仍可临时覆盖)。插件无 settings.json 写通道 (HostCapabilities\n * 无该面), 本文件键在其上, 即命令是比 settings 更近一次的显式表达。同时清\n * 除拒绝标记: 显式升/降档是最新的用户意图, 压过此前的\"对默认档说不\"。\n */\nexport function writeMemorySettingsMode(agentDir: string, mode: \"light\" | \"full\"): void {\n\tconst config = readMemoryAgentDirConfig(agentDir);\n\tconfig.memorySettingsMode = mode;\n\tdelete config.memoryConsent;\n\twriteMemoryAgentDirConfig(agentDir, config);\n}\n"]}

package/dist/memory/enabling.js

@@ -0,0 +1,321 @@
+/**
+ * enabling 前置检查、档位预设与镜像源（capability 拆分战役 slice 1）：纯函数,
+ * 无闭包依赖。
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { statfs } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { purgeZeroByteCacheArtifacts } from "./model-cache-hygiene.js";
+/** 开启前磁盘余量下限 (设计 §3.2 checking): light ≥ 500MB, full ≥ 2GB。 */
+export const DISK_HEADROOM_MIN_BYTES = {
+    light: 500 * 1024 * 1024,
+    full: 2 * 1024 * 1024 * 1024,
+};
+/**
+ * 模型文件大小下限 (防截断/空文件的 sanity 下限, 非精确体积): 高档 embedding
+ * (bge-m3 q8) 数百 MB → 下限 256MB, 精排器 (bge-reranker-base q8) ~280MB →
+ * 下限 64MB, 低档 (bge-small-zh q8) ~24MB → 下限 8MB。真实校验由加载冒烟承担。
+ */
+export const MODEL_MIN_WEIGHT_BYTES = {
+    light: 8 * 1024 * 1024,
+    full: 256 * 1024 * 1024,
+};
+export const RERANKER_MIN_WEIGHT_BYTES = 64 * 1024 * 1024;
+/** 自定义镜像源环境变量 (失败行动清单第一项指向它)。 */
+const HF_MIRRORS_ENV = "AGENT_FORGE_HF_MIRRORS";
+export const VECTOR_PRESET_LIGHT = {
+    embeddingModelId: "Xenova/bge-small-zh-v1.5",
+    dimensions: 512,
+    queryPrefix: "为这个句子生成表示以用于检索相关文章：",
+};
+export const VECTOR_PRESET_FULL = {
+    embeddingModelId: "Xenova/bge-m3",
+    dimensions: 1024,
+    queryPrefix: "",
+};
+/** 镜像序列 (实施计划 §7): 直连 huggingface.co 超时时回落 hf-mirror.com。 */
+const VECTOR_REMOTE_HOSTS = ["https://huggingface.co", "https://hf-mirror.com"];
+/** 档位预设: mode → 模型组合。off 在进入装配前已被门控拦截。 */
+export function vectorPresetForMode(mode) {
+    return mode === "light" ? VECTOR_PRESET_LIGHT : VECTOR_PRESET_FULL;
+}
+/**
+ * agentDir 身份归一化 (2026-10-06 串线修复): 绝对路径解析抹平分隔符与相对段,
+ * win32 再 casefold —— 同一目录在 Windows 下的大小写差异 (盘符/路径段) 不得
+ * 误判为跨 agent-dir 串线。仅用于身份比对, 不触碰文件系统语义。
+ */
+export function normalizeMemoryAgentDirIdentity(agentDir) {
+    const resolvedPath = resolve(agentDir);
+    return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
+}
+/**
+ * 自定义镜像源 (失败行动清单第一项指向它): env `AGENT_FORGE_HF_MIRRORS` 逗号
+ * 分隔 host 列表, 排在默认镜像序列之前优先尝试; 默认序列直连 huggingface.co
+ * 超时时回落 hf-mirror.com。
+ *
+ * env 条目归一化 (2026-10-06 live E2E 修复): 裸主机名补 `https://` — 用户
+ * 按行动清单写 `AGENT_FORGE_HF_MIRRORS=hf-mirror.com` 时, 无 scheme 的
+ * remoteHost 会让 transformers 的文件请求按相对 URL 解析并在模块内留下
+ * 毒化状态, 连后续带 scheme 的镜像重试也崩; 行动清单推荐的自救手段本身
+ * 不能是断的。已带 scheme 的条目原样保留, 尾部 `/` 去除。
+ */
+export function remoteHostsForEnabling() {
+    const custom = process.env[HF_MIRRORS_ENV]
+        ?.split(",")
+        .map((host) => host.trim().replace(/\/+$/, ""))
+        .map((host) => (host === "" || host.includes("://") ? host : `https://${host}`))
+        .filter((host) => host !== "");
+    return custom === undefined || custom.length === 0 ? VECTOR_REMOTE_HOSTS : [...custom, ...VECTOR_REMOTE_HOSTS];
+}
+/**
+ * 本地检查 1: native .node sidecar 可解析 (设计 §3.2 checking)。布局:
+ * onnxruntime-node/bin 下的 napi-vN/<platform>/<arch> 原生模块 — 缺失 = 安装
+ * 损坏。容错: 不钉死 napi 版本号, 逐目录扫描。
+ *
+ * 解析基点双通道: jiti（安装店加载缝）注入的 `require` 走宿主 alias 表
+ * （宿主 node_modules 副本, 店内无依赖树）; 纯 ESM（源码/工作区直载）下裸
+ * `require` 未定义（typeof 探测不抛 ReferenceError）, 回落原生 createRequire。
+ */
+function resolveOnnxRuntimeEntryPath() {
+    if (typeof require === "function") {
+        try {
+            return require.resolve("onnxruntime-node");
+        }
+        catch {
+            // jiti 解析失败（alias 未覆盖等）→ 继续走原生解析再报结构化错误。
+        }
+    }
+    return createRequire(import.meta.url).resolve("onnxruntime-node");
+}
+export function nativeBinaryCheck(hostEntryPath) {
+    // 两种失败要区分 (D-075 安装店路径修复后前者成为真实可达路径):
+    // (a) 宿主未注入入口路径且插件位置自解析不到 — 不是安装损坏, 行动是宿主侧
+    //     安装重依赖后重启会话, 不是重装插件;
+    // (b) 路径存在但原生二进制缺失/损坏 — 保留损坏类文案。
+    let entryPath;
+    if (hostEntryPath === undefined) {
+        try {
+            entryPath = resolveOnnxRuntimeEntryPath();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            return `onnxruntime-node is not provided by the host installation and could not be resolved from the plugin location (${detail}); to enable memory features, install onnxruntime-node in the host project (npm i onnxruntime-node) and restart the session`;
+        }
+    }
+    else {
+        entryPath = hostEntryPath;
+    }
+    try {
+        let packageDir = dirname(entryPath);
+        while (packageDir !== dirname(packageDir) && !existsSync(join(packageDir, "package.json"))) {
+            packageDir = dirname(packageDir);
+        }
+        const binDir = join(packageDir, "bin");
+        if (!existsSync(binDir))
+            return `onnxruntime native binary directory not found: ${binDir}`;
+        for (const napiEntry of readdirSync(binDir, { withFileTypes: true })) {
+            if (!napiEntry.isDirectory() || !napiEntry.name.startsWith("napi-v"))
+                continue;
+            const platformDir = join(binDir, napiEntry.name, process.platform, process.arch);
+            if (!existsSync(platformDir))
+                continue;
+            const binaries = readdirSync(platformDir).filter((file) => file.endsWith(".node"));
+            if (binaries.length > 0)
+                return undefined;
+        }
+        return `onnxruntime native binary for ${process.platform}/${process.arch} not found under ${binDir}`;
+    }
+    catch (error) {
+        return `onnxruntime native binary could not be resolved (${error instanceof Error ? error.message : String(error)}); the installation looks damaged — reinstall the package`;
+    }
+}
+/**
+ * 重依赖自解析默认实现 (missingHeavyDependencyModules 生产接线): 双通道与
+ * {@link resolveOnnxRuntimeEntryPath} 一致 — jiti（安装店加载缝）注入的
+ * `require` 走宿主 alias 表; 纯 ESM（源码/工作区直载）下回落原生 createRequire。
+ */
+export function resolveHeavyDependencyEntryPath(specifier) {
+    if (typeof require === "function") {
+        try {
+            return require.resolve(specifier);
+        }
+        catch {
+            // jiti 解析失败（alias 未覆盖等）→ 继续走原生解析。
+        }
+    }
+    return createRequire(import.meta.url).resolve(specifier);
+}
+/**
+ * 本地检查 1b: 重依赖供给 (设计 §3.2 checking)。`@lancedb/lancedb` 与
+ * `@huggingface/transformers` 逐个判定 — entries 提供宿主入口路径 = 可用
+ * (不触自解析); 未提供时 resolveModule 自解析成功 = 可用, 抛错 = 计入缺失。
+ * 返回缺失 specifier 列表 (空 = 通过)。纯函数零 IO; 导出仅供测试 (与宿主侧
+ * buildHostDependencyAliases 同一模式), 生产接线传插件位置自解析 — 把加载步
+ * 的 "Cannot find module" 泛化包装前置成精准缺供文案, 省掉模型下载等前置工作。
+ */
+export function missingHeavyDependencyModules(entries, resolveModule) {
+    const missing = [];
+    const supplies = [
+        ["@lancedb/lancedb", entries.lancedb],
+        ["@huggingface/transformers", entries.transformers],
+    ];
+    for (const [specifier, entryPath] of supplies) {
+        if (entryPath !== undefined)
+            continue;
+        try {
+            resolveModule(specifier);
+        }
+        catch {
+            missing.push(specifier);
+        }
+    }
+    return missing;
+}
+/**
+ * transformers.js 缓存布局的容错存在性检查 (设计 §3.2 手动导入路径):
+ * `<cacheDir>/<modelId>/` 下需有非空 tokenizer 文件与 `onnx/` 权重文件。
+ * 返回 undefined = 检查通过; "missing" = 目录/文件缺失或仅剩 0 字节残骸
+ * (失败下载产物, 清理后进入下载阶段, 见 model-cache-hygiene); 其他字符串 =
+ * 文件存在但可疑 (截断/非空过小), 属失败。
+ */
+export function modelFilesCheck(cacheDir, modelId, minWeightBytes) {
+    const modelDir = join(cacheDir, modelId);
+    if (!existsSync(modelDir))
+        return "missing";
+    // tokenizer 只剩 0 字节文件 = 失败下载残骸 (真 tokenizer.json 不可能为空):
+    // 清掉按缺失处理可重下; 非空文件不动 (手动导入布局不受影响)。
+    const tokenizerNames = ["tokenizer.json", "tokenizer.model"].filter((name) => existsSync(join(modelDir, name)));
+    const hasTokenizer = tokenizerNames.some((name) => statSync(join(modelDir, name)).size > 0);
+    if (!hasTokenizer) {
+        if (tokenizerNames.length > 0)
+            purgeZeroByteCacheArtifacts(modelDir);
+        return "missing";
+    }
+    const onnxDir = join(modelDir, "onnx");
+    if (!existsSync(onnxDir))
+        return `onnx weight directory missing under ${modelDir}`;
+    const weights = readdirSync(onnxDir).filter((name) => name.includes(".onnx"));
+    if (weights.length === 0)
+        return `no onnx weight file under ${onnxDir}`;
+    const largest = Math.max(...weights.map((name) => statSync(join(onnxDir, name)).size));
+    if (largest < minWeightBytes) {
+        return `largest onnx weight under ${onnxDir} is ${largest} bytes, below the expected minimum ${minWeightBytes} — the download looks truncated`;
+    }
+    return undefined;
+}
+/**
+ * 本地检查 3: 磁盘余量 (设计 §3.2 checking, node:fs statfs, 零新依赖)。
+ * 以 agentDir 所在卷为准 (cacheDir 同卷创建)。agentDir 可能尚不存在 (全新
+ * 机器首启, 下载前无人创建过它 — 2026-10-06 live E2E 实测踩中) — statfs
+ * ENOENT 时逐级上溯最近存在的祖先目录, 同卷即同余量; 上溯到根仍失败才按
+ * 无法判定报告。
+ */
+export async function diskHeadroomCheck(agentDir, minimumBytes) {
+    let freeBytes;
+    let probe = agentDir;
+    for (let attempt = 0; probe !== undefined && attempt < 16; attempt++) {
+        try {
+            const stats = await statfs(probe);
+            freeBytes = stats.bfree * stats.bsize;
+            break;
+        }
+        catch (error) {
+            if (!(error instanceof Error) || !String(error.message).includes("ENOENT")) {
+                return `disk free space could not be determined for ${agentDir} (probing ${probe}: ${error instanceof Error ? error.message : String(error)})`;
+            }
+            const parent = dirname(probe);
+            probe = parent === probe ? undefined : parent;
+        }
+    }
+    if (freeBytes === undefined) {
+        return `disk free space could not be determined for ${agentDir} (no existing ancestor directory to statfs)`;
+    }
+    if (freeBytes < minimumBytes) {
+        return `disk free space is ${freeBytes} bytes, below the required ${minimumBytes}`;
+    }
+    return undefined;
+}
+/** enabling 失败的五选一行动清单 (设计 §3.2 硬性要求)。 */
+export function enablingActionList(modelCacheDir, currentMode) {
+    return [
+        `Switch to a reachable mirror: set ${HF_MIRRORS_ENV} to a comma-separated host list (tried before the defaults)`,
+        `Install the heavy dependencies in the host project (npm i onnxruntime-node @lancedb/lancedb @huggingface/transformers) so the host can supply them via hostDependencyPaths, then restart the session`,
+        `Download the models manually and place them under ${modelCacheDir} (layout: <modelId>/tokenizer.json + <modelId>/onnx/model*.onnx)`,
+        currentMode === "full"
+            ? 'Downgrade to memory.mode "light" (much smaller models)'
+            : 'Keep memory.mode "light" and retry with a reachable mirror',
+        'Give up: leave memory.mode "off" (the default) so the memory family stays unregistered',
+    ];
+}
+// ---------------------------------------------------------------------------
+// 征询持久化 (capability 拆分战役 slice 3b 随迁, 征询域): agent-dir 配置文件
+// 的读写与征询拒绝/档位落盘。纯函数, 路径域显式传入; capability.ts 经
+// re-export 维持历史导出面, 向量通道 (vector-channel.ts) 直接 import。
+// ---------------------------------------------------------------------------
+/** agent-dir 配置文件里的征询拒绝标记值 (memoryConsent 键)。 */
+export const MEMORY_CONSENT_DECLINED_VALUE = "declined";
+/** memory 插件 agent-dir 配置通道 (entry 读、capability 写, 同一路径)。 */
+export const MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH = join("capabilities", "builtin.memory.json");
+function readMemoryAgentDirConfig(agentDir) {
+    const configPath = join(agentDir, MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH);
+    if (existsSync(configPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(configPath, "utf8"));
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // 既有文件非法时以本次写入为准 (持久化是显式用户动作, 不被脏文件阻塞)。
+        }
+    }
+    return {};
+}
+/**
+ * 写 agent-dir 配置的原子替换 (2026-10-06 复审 P1-2): temp 文件 + rename —
+ * 自动升档引入了无人值守写者, 与其它进程的 /memory off (会删档位键) 读改写
+ * 交错时, 直接 writeFileSync 可能留下半截 JSON 让并发读者拿到空配置 (整块
+ * 丢键: 抹掉并发 decline 或升档)。rename 在同一目录内原子替换, 读者要么见
+ * 旧文件要么见新文件。
+ */
+function writeMemoryAgentDirConfig(agentDir, config) {
+    const configPath = join(agentDir, MEMORY_AGENT_DIR_CONFIG_RELATIVE_PATH);
+    mkdirSync(dirname(configPath), { recursive: true });
+    const tempPath = `${configPath}.${process.pid}.tmp`;
+    writeFileSync(tempPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+    renameSync(tempPath, configPath);
+}
+/** agent-dir 配置里用户显式持久化的档位键 (无 / 该键即 undefined)。 */
+export function readMemorySettingsMode(agentDir) {
+    const value = readMemoryAgentDirConfig(agentDir).memorySettingsMode;
+    return value === "light" || value === "full" ? value : undefined;
+}
+/**
+ * 拒绝/跳过的持久化 (2026-10-05 用户裁决): 写入插件自己的 agent-dir 配置文件,
+ * 不改写用户 settings.json。语义是「用户对默认档说了不」——仅抑制默认档;
+ * 用户日后显式设置 settings.json `memory.mode` (light/full) 时显式值仍然生效。
+ * 同时移除 /memory light|full 持久化的档位键, 保证"先升 full 再 off"不会留下
+ * 一个压过 settings 的陈旧档位。
+ */
+export function writeMemoryConsentDeclined(agentDir) {
+    const config = readMemoryAgentDirConfig(agentDir);
+    config.memoryConsent = MEMORY_CONSENT_DECLINED_VALUE;
+    delete config.memorySettingsMode;
+    delete config.memoryMode;
+    writeMemoryAgentDirConfig(agentDir, config);
+}
+/**
+ * 档位升级/降级的持久化 (/memory light|full): 写入插件 agent-dir 配置的
+ * `memorySettingsMode` 键——与 settings.json `memory.mode` 同一解析层 (持久
+ * 配置面, env 仍可临时覆盖)。插件无 settings.json 写通道 (HostCapabilities
+ * 无该面), 本文件键在其上, 即命令是比 settings 更近一次的显式表达。同时清
+ * 除拒绝标记: 显式升/降档是最新的用户意图, 压过此前的"对默认档说不"。
+ */
+export function writeMemorySettingsMode(agentDir, mode) {
+    const config = readMemoryAgentDirConfig(agentDir);
+    config.memorySettingsMode = mode;
+    delete config.memoryConsent;
+    writeMemoryAgentDirConfig(agentDir, config);
+}
+//# sourceMappingURL=enabling.js.map