@ai-agent-forge/plugin-memory 0.88.1 → 0.88.4

package/dist/memory/inference-server.d.ts

@@ -0,0 +1,70 @@
+import type { MemoryEmbeddingProviderV1 } from "./embedding-provider.ts";
+import type { MemoryRerankerV1 } from "./embedding-reranker.ts";
+import type { MemoryVectorIndexV1 } from "./vector-index.ts";
+/**
+ * 逐请求看门狗阈值出厂默认 (2026-10-06): 大于客户端请求超时 (装配缝 60s /
+ * 客户端缺省 10s) — 正常慢操作先被客户端放弃, 服务端不打断。诚实约束: JS 侧
+ * 超时不中断底层原生调用 (ONNX 线程仍占住资源), 语义是"串行队列恢复推进、
+ * 后续请求可用", 不是后端取消。
+ */
+export declare const MEMORY_INFERENCE_REQUEST_WATCHDOG_MS = 120000;
+/**
+ * 连接活跃度阈值出厂默认 (2026-10-07, codex remote-control 同款先例): 自最近
+ * 收到帧起超过该时长且无在途请求的连接视为陈旧, 不再阻止空闲退出 — 挂起不退
+ * 的客户端 (逻辑死、socket 活) 不会把服务模型永久按驻内存。无协议面新增:
+ * 活跃度由服务端按帧到达自行观测, 客户端零改动。
+ */
+export declare const MEMORY_INFERENCE_CONNECTION_STALE_MS: number;
+/** 服务端持有的唯一推理后端 (生产 = 真实装配; 测试 = deterministic mock)。 */
+export interface MemoryInferenceBackendV1 {
+    readonly embedProvider: MemoryEmbeddingProviderV1;
+    readonly reranker?: MemoryRerankerV1;
+    readonly vectorIndex: MemoryVectorIndexV1;
+}
+export interface MemoryInferenceServerV1 {
+    /** 实际绑定端口 (port: 0 时为 OS 分配值 — 测试用; 生产固定端口即单例互斥)。 */
+    readonly port: number;
+    readonly host: string;
+    /**
+     * 优雅停机: 停止监听 → 排空串行队列 (在途响应写回) → 断开全部连接 → 关闭
+     * 索引句柄。幂等。
+     */
+    close(): Promise<void>;
+    /**
+     * 强制停机 (模拟进程死亡/紧急退出): 立即断开全部连接与在途请求 (客户端
+     * pending 全部结构化失败 — 设计 §4), 不等待队列排空。
+     */
+    destroy(): Promise<void>;
+    /** 服务完全关闭 (显式或空闲自杀) 后 resolve。 */
+    readonly closed: Promise<void>;
+}
+export interface MemoryInferenceServerOptions {
+    readonly backend: MemoryInferenceBackendV1;
+    /** 缺省 MEMORY_INFERENCE_DEFAULT_PORT; 0 = OS 分配 (测试)。同端口二次绑定 reject (单例互斥)。 */
+    readonly port?: number;
+    readonly host?: string;
+    /** 空闲自杀阈值 (无活跃连接且无在途请求)。缺省 0 = 不启用。出厂默认值登记产品默认值清单。 */
+    readonly idleTimeoutMs?: number;
+    /**
+     * 连接活跃度阈值 (2026-10-07): 见 MEMORY_INFERENCE_CONNECTION_STALE_MS。
+     * 缺省 10 分钟; 0 = 关闭 (任何连接都阻止空闲退出 — 原语义)。
+     */
+    readonly connectionStaleMs?: number;
+    /**
+     * 服务进程的 agent-dir 身份 (2026-10-06 串线修复): hello 握手回报给客户端,
+     * 会话装配据此拒绝跨 agent-dir 串线。缺省不上报 (旧版本 wire 兼容, 装配校验
+     * 按缺失拒绝); 生产服务经 runMemoryInferenceService 传入。
+     */
+    readonly agentDir?: string;
+    /**
+     * 逐请求看门狗阈值: 后端派发超过该时长即对该请求返回结构化 backend_error,
+     * 串行队列继续推进 (不中断底层原生调用 — 见
+     * MEMORY_INFERENCE_REQUEST_WATCHDOG_MS 注释)。缺省 120s; 测试注入小值。
+     */
+    readonly requestWatchdogMs?: number;
+    readonly signal?: AbortSignal;
+    /** 结构化错误面 (日志/诊断); 不抛出 — 服务端错误一律转为 error 响应或告警。 */
+    readonly onError?: (error: Error, context: string) => void;
+}
+export declare function createMemoryInferenceServer(options: MemoryInferenceServerOptions): Promise<MemoryInferenceServerV1>;
+//# sourceMappingURL=inference-server.d.ts.map

package/dist/memory/inference-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-server.d.ts","sourceRoot":"","sources":["../../src/memory/inference-server.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAWhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,SAAU,CAAC;AAE5D;;;;;GAKG;AACH,eAAO,MAAM,oCAAoC,QAAiB,CAAC;AAKnE,mGAAyD;AACzD,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,aAAa,EAAE,yBAAyB,CAAC;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;CAC1C;AAED,MAAM,WAAW,uBAAuB;IACvC,2GAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,gEAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,oHAA8E;IAC9E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oIAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,6GAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAwWnH","sourcesContent":["/**\n * 记忆共享推理服务 — 服务端 (记忆共享推理服务设计 §3.1/§3.4/§3.5)。\n *\n * 常驻 sidecar 的服务端面: 持有唯一的推理后端 (embedProvider/reranker/\n * vectorIndex — 生产装配为真实 transformers + LanceDB, 测试注入 deterministic\n * mock), 经 TCP loopback 服务 `inference-protocol.ts` 的消息面。\n *\n * 串行化 (设计 §3.4): 所有请求经单条 promise 链按到达序执行 — LanceDB 表\n * 创建与 ONNX 管线未声明并发安全, 单用户量级下串行的吞吐足够, 正确性优先\n * (同一理由: 每进程一个 vectorQueue 的既有先例)。\n *\n * 逐请求看门狗 (2026-10-06, 设计 §3.4): 后端派发超过 requestWatchdogMs\n * (缺省 MEMORY_INFERENCE_REQUEST_WATCHDOG_MS) 即对该请求返回结构化\n * backend_error, 串行队列恢复推进 — 后端永不落定时 (如 ONNX 挂起) 其余请求\n * 不再排队等死。诚实约束: JS 侧超时不中断底层原生调用 (ONNX 线程仍占住),\n * 语义是\"队列恢复推进、后续请求可用\", 不是后端取消。\n *\n * 生命周期 (设计 §3.5): 空闲自杀 — 无活跃连接且无在途请求持续 idleTimeoutMs 后\n * 优雅关闭 (端口让出, 下一个使用者重新拉起); 新连接取消计时。活跃 = 有在途请求,\n * 或最近收到帧距今未超过连接活跃度阈值 (connectionStaleMs): 挂起不退的客户端\n * (逻辑死、socket 活) 不再把空闲退出永久按住, 由周期清扫重估。close() 供\n * 进程入口与测试显式停机。\n */\nimport { createServer, type Server, type Socket } from \"node:net\";\nimport { FrameDecoder } from \"@agent-forge/protocol\";\nimport type { MemoryEmbeddingProviderV1 } from \"./embedding-provider.ts\";\nimport type { MemoryRerankerV1 } from \"./embedding-reranker.ts\";\nimport {\n\tdecodeInferenceMessage,\n\tencodeInferenceMessage,\n\tMEMORY_INFERENCE_DEFAULT_HOST,\n\tMEMORY_INFERENCE_DEFAULT_PORT,\n\tMEMORY_INFERENCE_PROTOCOL_VERSION,\n\ttype MemoryInferenceHelloResultV1,\n\ttype MemoryInferenceRequestV1,\n\ttype MemoryInferenceResponseV1,\n} from \"./inference-protocol.ts\";\nimport type { MemoryVectorIndexV1 } from \"./vector-index.ts\";\n\n/**\n * 逐请求看门狗阈值出厂默认 (2026-10-06): 大于客户端请求超时 (装配缝 60s /\n * 客户端缺省 10s) — 正常慢操作先被客户端放弃, 服务端不打断。诚实约束: JS 侧\n * 超时不中断底层原生调用 (ONNX 线程仍占住资源), 语义是\"串行队列恢复推进、\n * 后续请求可用\", 不是后端取消。\n */\nexport const MEMORY_INFERENCE_REQUEST_WATCHDOG_MS = 120_000;\n\n/**\n * 连接活跃度阈值出厂默认 (2026-10-07, codex remote-control 同款先例): 自最近\n * 收到帧起超过该时长且无在途请求的连接视为陈旧, 不再阻止空闲退出 — 挂起不退\n * 的客户端 (逻辑死、socket 活) 不会把服务模型永久按驻内存。无协议面新增:\n * 活跃度由服务端按帧到达自行观测, 客户端零改动。\n */\nexport const MEMORY_INFERENCE_CONNECTION_STALE_MS = 10 * 60 * 1000;\n\n/** 陈旧连接清扫周期上限; 实际取 min(本值, 阈值/2), 测试注入短阈值即得短周期。 */\nconst CONNECTION_STALE_SWEEP_MAX_MS = 30_000;\n\n/** 服务端持有的唯一推理后端 (生产 = 真实装配; 测试 = deterministic mock)。 */\nexport interface MemoryInferenceBackendV1 {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker?: MemoryRerankerV1;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n}\n\nexport interface MemoryInferenceServerV1 {\n\t/** 实际绑定端口 (port: 0 时为 OS 分配值 — 测试用; 生产固定端口即单例互斥)。 */\n\treadonly port: number;\n\treadonly host: string;\n\t/**\n\t * 优雅停机: 停止监听 → 排空串行队列 (在途响应写回) → 断开全部连接 → 关闭\n\t * 索引句柄。幂等。\n\t */\n\tclose(): Promise<void>;\n\t/**\n\t * 强制停机 (模拟进程死亡/紧急退出): 立即断开全部连接与在途请求 (客户端\n\t * pending 全部结构化失败 — 设计 §4), 不等待队列排空。\n\t */\n\tdestroy(): Promise<void>;\n\t/** 服务完全关闭 (显式或空闲自杀) 后 resolve。 */\n\treadonly closed: Promise<void>;\n}\n\nexport interface MemoryInferenceServerOptions {\n\treadonly backend: MemoryInferenceBackendV1;\n\t/** 缺省 MEMORY_INFERENCE_DEFAULT_PORT; 0 = OS 分配 (测试)。同端口二次绑定 reject (单例互斥)。 */\n\treadonly port?: number;\n\treadonly host?: string;\n\t/** 空闲自杀阈值 (无活跃连接且无在途请求)。缺省 0 = 不启用。出厂默认值登记产品默认值清单。 */\n\treadonly idleTimeoutMs?: number;\n\t/**\n\t * 连接活跃度阈值 (2026-10-07): 见 MEMORY_INFERENCE_CONNECTION_STALE_MS。\n\t * 缺省 10 分钟; 0 = 关闭 (任何连接都阻止空闲退出 — 原语义)。\n\t */\n\treadonly connectionStaleMs?: number;\n\t/**\n\t * 服务进程的 agent-dir 身份 (2026-10-06 串线修复): hello 握手回报给客户端,\n\t * 会话装配据此拒绝跨 agent-dir 串线。缺省不上报 (旧版本 wire 兼容, 装配校验\n\t * 按缺失拒绝); 生产服务经 runMemoryInferenceService 传入。\n\t */\n\treadonly agentDir?: string;\n\t/**\n\t * 逐请求看门狗阈值: 后端派发超过该时长即对该请求返回结构化 backend_error,\n\t * 串行队列继续推进 (不中断底层原生调用 — 见\n\t * MEMORY_INFERENCE_REQUEST_WATCHDOG_MS 注释)。缺省 120s; 测试注入小值。\n\t */\n\treadonly requestWatchdogMs?: number;\n\treadonly signal?: AbortSignal;\n\t/** 结构化错误面 (日志/诊断); 不抛出 — 服务端错误一律转为 error 响应或告警。 */\n\treadonly onError?: (error: Error, context: string) => void;\n}\n\nexport function createMemoryInferenceServer(options: MemoryInferenceServerOptions): Promise<MemoryInferenceServerV1> {\n\tconst host = options.host ?? MEMORY_INFERENCE_DEFAULT_HOST;\n\tconst idleTimeoutMs = options.idleTimeoutMs ?? 0;\n\tconst connectionStaleMs = options.connectionStaleMs ?? MEMORY_INFERENCE_CONNECTION_STALE_MS;\n\tconst requestWatchdogMs = options.requestWatchdogMs ?? MEMORY_INFERENCE_REQUEST_WATCHDOG_MS;\n\tlet idleTimer: NodeJS.Timeout | undefined;\n\tconst sockets = new Set<Socket>();\n\t// 连接活跃度 (2026-10-07): 每连接最近帧到达时刻 + 在途请求数。活跃 = 有在途\n\t// 请求 (帧可能早于陈旧阈值 — 串行队列排队/后端慢不算挂起), 或最近帧未超阈。\n\tconst socketStates = new Map<Socket, { lastFrameAt: number; pendingRequests: number }>();\n\tlet closed = false;\n\tlet closeResolve: (() => void) | undefined;\n\tconst closedPromise = new Promise<void>((resolve) => {\n\t\tcloseResolve = resolve;\n\t});\n\t// 全局串行队列: 所有连接的全部请求按到达序执行 (设计 §3.4)。\n\tlet queueTail: Promise<void> = Promise.resolve();\n\tconst enqueue = (operation: () => Promise<void>): Promise<void> => {\n\t\tconst next = queueTail.then(operation, operation);\n\t\tqueueTail = next.catch(() => undefined);\n\t\treturn next;\n\t};\n\t// 逐请求看门狗 (2026-10-06): 包住单次后端派发, 超时即返回结构化 backend_error,\n\t// 让串行队列的当前位置落定 — 后端 promise 永不落定时 (如 ONNX 挂起) 后续请求\n\t// 不再排队等死。诚实约束: 超时只是不再等待, 底层原生调用无法被中断 (ONNX\n\t// 线程仍占住资源), 语义是\"队列恢复推进、后续请求可用\", 不是后端取消; 输掉\n\t// 竞速的 handleRequest 在后台落定, 其迟到结果被丢弃 (连接可能已亡, write\n\t// 错误走 socket error 处理)。\n\tconst withRequestWatchdog = (\n\t\trequest: MemoryInferenceRequestV1,\n\t\toperation: Promise<MemoryInferenceResponseV1>,\n\t): Promise<MemoryInferenceResponseV1> => {\n\t\tlet watchdog: NodeJS.Timeout | undefined;\n\t\tconst expired = new Promise<MemoryInferenceResponseV1>((resolve) => {\n\t\t\twatchdog = setTimeout(() => {\n\t\t\t\tresolve({\n\t\t\t\t\tkind: \"error\",\n\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\tmessage: `memory inference backend timed out after ${requestWatchdogMs}ms (request kind=${request.kind})`,\n\t\t\t\t});\n\t\t\t}, requestWatchdogMs);\n\t\t\twatchdog.unref?.();\n\t\t});\n\t\treturn Promise.race([operation, expired]).finally(() => clearTimeout(watchdog));\n\t};\n\n\tconst server: Server = createServer((socket: Socket) => {\n\t\tsockets.add(socket);\n\t\tsocketStates.set(socket, { lastFrameAt: Date.now(), pendingRequests: 0 });\n\t\tif (idleTimer !== undefined) {\n\t\t\tclearTimeout(idleTimer);\n\t\t\tidleTimer = undefined;\n\t\t}\n\t\tconst decoder = new FrameDecoder();\n\t\t// 响应写回 (2026-10-06): 超过 16MB 帧/CBOR 上限的响应 (如 full 档大包\n\t\t// embed) 无法原样编码, 编码抛错若不接住会被 enqueue 的队列兜底 catch 吞\n\t\t// 掉 — 客户端吃满请求超时且根因不可见。回小体量结构化错误帧让客户端\n\t\t// 立刻拿到根因并收缩批量; 错误帧自身再失败只能断连 (socket 已不可写)。\n\t\tconst writeResponse = (response: MemoryInferenceResponseV1, endAfter: boolean): void => {\n\t\t\tlet payload = response;\n\t\t\tlet bytes: Uint8Array;\n\t\t\ttry {\n\t\t\t\tbytes = encodeInferenceMessage(payload);\n\t\t\t} catch (encodeError) {\n\t\t\t\toptions.onError?.(\n\t\t\t\t\tencodeError instanceof Error ? encodeError : new Error(String(encodeError)),\n\t\t\t\t\t\"inference-server:encode\",\n\t\t\t\t);\n\t\t\t\ttry {\n\t\t\t\t\tpayload = {\n\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\trequestId: response.requestId,\n\t\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\t\tmessage: `memory inference response exceeds the wire frame limit; shrink the batch (${\n\t\t\t\t\t\t\tencodeError instanceof Error ? encodeError.message : String(encodeError)\n\t\t\t\t\t\t})`,\n\t\t\t\t\t};\n\t\t\t\t\tbytes = encodeInferenceMessage(payload);\n\t\t\t\t} catch {\n\t\t\t\t\tsocket.destroy();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t\tsocket.write(bytes, endAfter ? () => socket.end() : undefined);\n\t\t};\n\t\tsocket.on(\"data\", (chunk: Buffer) => {\n\t\t\t// 任何字节到达都是活跃度证据 (坏帧连接随后即被断开, 无所谓)。\n\t\t\tconst socketState = socketStates.get(socket);\n\t\t\tif (socketState !== undefined) socketState.lastFrameAt = Date.now();\n\t\t\t// 帧层异常必须捕获 (复审 P2-1): 声明长度超限的帧在 data 监听器抛\n\t\t\t// FrameError 即 uncaughtException — 坏帧/合法超大帧可干死服务进程。\n\t\t\t// 先例: subagent/stdio-channel.ts 同款处理。\n\t\t\tlet frames: Uint8Array[];\n\t\t\ttry {\n\t\t\t\tframes = decoder.push(new Uint8Array(chunk));\n\t\t\t} catch (error) {\n\t\t\t\toptions.onError?.(error instanceof Error ? error : new Error(String(error)), \"inference-server:frame\");\n\t\t\t\tsocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tfor (const frame of frames) {\n\t\t\t\tif (frame.byteLength === 0) continue;\n\t\t\t\tlet request: MemoryInferenceRequestV1;\n\t\t\t\ttry {\n\t\t\t\t\trequest = decodeInferenceMessage(frame) as MemoryInferenceRequestV1;\n\t\t\t\t} catch (error) {\n\t\t\t\t\toptions.onError?.(error instanceof Error ? error : new Error(String(error)), \"inference-server:decode\");\n\t\t\t\t\tsocket.end();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (socketState !== undefined) socketState.pendingRequests += 1;\n\t\t\t\tvoid enqueue(() =>\n\t\t\t\t\twithRequestWatchdog(request, handleRequest(request)).then(\n\t\t\t\t\t\t(response) => {\n\t\t\t\t\t\t\t// 优雅停机期间在途响应仍写回 (close 先排空队列再断连);\n\t\t\t\t\t\t\t// socket 已亡时 write 错误走 socket error 处理。\n\t\t\t\t\t\t\tif (response.kind === \"error\" && response.code === \"protocol_version\") {\n\t\t\t\t\t\t\t\twriteResponse(response, true);\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\twriteResponse(response, false);\n\t\t\t\t\t\t},\n\t\t\t\t\t\t() => undefined,\n\t\t\t\t\t),\n\t\t\t\t).finally(() => {\n\t\t\t\t\tif (socketState !== undefined) socketState.pendingRequests -= 1;\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\t\tconst drop = () => {\n\t\t\tsocket.destroy();\n\t\t};\n\t\tsocket.on(\"error\", (error) => {\n\t\t\toptions.onError?.(error, \"inference-server:socket\");\n\t\t\tdrop();\n\t\t});\n\t\tsocket.on(\"close\", () => {\n\t\t\tsockets.delete(socket);\n\t\t\tsocketStates.delete(socket);\n\t\t\tmaybeScheduleIdleExit();\n\t\t});\n\t});\n\n\t/**\n\t * 活跃连接数: 有在途请求, 或最近帧距现在未超过活跃度阈值的连接。\n\t * connectionStaleMs <= 0 时退化为全部连接 (原语义)。\n\t */\n\tconst activeConnectionCount = (): number => {\n\t\tif (connectionStaleMs <= 0) return sockets.size;\n\t\tconst nowMs = Date.now();\n\t\tlet active = 0;\n\t\tfor (const socket of sockets) {\n\t\t\tconst state = socketStates.get(socket);\n\t\t\tif (state === undefined) continue;\n\t\t\tif (state.pendingRequests > 0 || nowMs - state.lastFrameAt < connectionStaleMs) active += 1;\n\t\t}\n\t\treturn active;\n\t};\n\n\tconst handleRequest = async (request: MemoryInferenceRequestV1): Promise<MemoryInferenceResponseV1> => {\n\t\ttry {\n\t\t\tswitch (request.kind) {\n\t\t\t\tcase \"hello\": {\n\t\t\t\t\tif (request.protocolVersion !== MEMORY_INFERENCE_PROTOCOL_VERSION) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\t\tcode: \"protocol_version\",\n\t\t\t\t\t\t\tmessage: `inference protocol version mismatch: server=${MEMORY_INFERENCE_PROTOCOL_VERSION} client=${request.protocolVersion}`,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\t// agentDir 身份上报 (2026-10-06 串线修复): 有则带 (生产经\n\t\t\t\t\t// runMemoryInferenceService 传入), 无则不带 — 直连本工厂的旧\n\t\t\t\t\t// 测试缝与升级过渡期的旧版本服务进程保持 wire 兼容, 会话装配\n\t\t\t\t\t// 按字段缺失拒绝 (设计 §3.2)。\n\t\t\t\t\tconst helloBase = {\n\t\t\t\t\t\tprotocolVersion: MEMORY_INFERENCE_PROTOCOL_VERSION,\n\t\t\t\t\t\tembeddingModelId: options.backend.embedProvider.modelId,\n\t\t\t\t\t\tdimensions: options.backend.embedProvider.dimensions,\n\t\t\t\t\t\trerankerModelId: options.backend.reranker?.modelId ?? null,\n\t\t\t\t\t};\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: \"ok\",\n\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\tresult:\n\t\t\t\t\t\t\toptions.agentDir === undefined\n\t\t\t\t\t\t\t\t? (helloBase as MemoryInferenceHelloResultV1)\n\t\t\t\t\t\t\t\t: { ...helloBase, agentDir: options.agentDir },\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tcase \"embed\": {\n\t\t\t\t\tconst vectors = await options.backend.embedProvider.embed(request.texts);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { vectors } };\n\t\t\t\t}\n\t\t\t\tcase \"rerank\": {\n\t\t\t\t\tif (options.backend.reranker === undefined) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\t\t\tmessage: \"inference server has no reranker\",\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst scores = await options.backend.reranker.rerank(request.query, request.docs);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { scores } };\n\t\t\t\t}\n\t\t\t\tcase \"queryKnn\": {\n\t\t\t\t\tconst hits = await options.backend.vectorIndex.queryKnn(request.vector, request.query);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { hits } };\n\t\t\t\t}\n\t\t\t\tcase \"queryFts\": {\n\t\t\t\t\tconst hits = await options.backend.vectorIndex.queryFts(request.queryText, request.query);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { hits } };\n\t\t\t\t}\n\t\t\t\tcase \"upsert\": {\n\t\t\t\t\tawait options.backend.vectorIndex.upsert(request.entries);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\t}\n\t\t\t\tcase \"remove\": {\n\t\t\t\t\tawait options.backend.vectorIndex.remove(request.memoryIds);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\t}\n\t\t\t\tcase \"listMemoryIds\": {\n\t\t\t\t\tconst ids = await options.backend.vectorIndex.listMemoryIds();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { memoryIds: [...ids] } };\n\t\t\t\t}\n\t\t\t\tcase \"count\": {\n\t\t\t\t\tconst count = await options.backend.vectorIndex.count();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { count } };\n\t\t\t\t}\n\t\t\t\tcase \"getStoredModelId\": {\n\t\t\t\t\tconst modelId = await options.backend.vectorIndex.getStoredModelId();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { modelId: modelId ?? null } };\n\t\t\t\t}\n\t\t\t\tcase \"ping\":\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\tdefault:\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\trequestId: (request as { requestId: number }).requestId,\n\t\t\t\t\t\tcode: \"bad_request\",\n\t\t\t\t\t\tmessage: `unknown inference request kind: ${(request as { kind: string }).kind}`,\n\t\t\t\t\t};\n\t\t\t}\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tkind: \"error\",\n\t\t\t\trequestId: request.requestId,\n\t\t\t\tcode: \"backend_error\",\n\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t};\n\t\t}\n\t};\n\n\tconst maybeScheduleIdleExit = (): void => {\n\t\tif (closed || idleTimeoutMs <= 0 || activeConnectionCount() > 0 || idleTimer !== undefined) return;\n\t\tidleTimer = setTimeout(() => {\n\t\t\tidleTimer = undefined;\n\t\t\tif (activeConnectionCount() > 0 || closed) return;\n\t\t\tvoid finishClose(\"idle\", true);\n\t\t}, idleTimeoutMs);\n\t\tidleTimer.unref?.();\n\t};\n\n\t// 陈旧连接清扫 (2026-10-07): 活跃→陈旧的转变没有事件 (挂起客户端不发帧也\n\t// 不断连), 靠周期扫描重估空闲退出。周期取 min(30s, 阈值/2) — 生产 30s,\n\t// 测试注入短阈值即得短周期。仅在空闲退出与活跃度阈值都启用时运转。\n\tlet staleSweepTimer: NodeJS.Timeout | undefined;\n\tconst startStaleSweep = (): void => {\n\t\tif (closed || idleTimeoutMs <= 0 || connectionStaleMs <= 0 || staleSweepTimer !== undefined) {\n\t\t\treturn;\n\t\t}\n\t\tconst sweepIntervalMs = Math.min(CONNECTION_STALE_SWEEP_MAX_MS, Math.max(1, Math.floor(connectionStaleMs / 2)));\n\t\tstaleSweepTimer = setInterval(() => {\n\t\t\tif (!closed) maybeScheduleIdleExit();\n\t\t}, sweepIntervalMs);\n\t\tstaleSweepTimer.unref?.();\n\t};\n\n\tlet finishPromise: Promise<void> | undefined;\n\tconst finishClose = (reason: string, drain: boolean): Promise<void> => {\n\t\t// 并发调用统一返回同一次停机 (复审 P3-5): 后到的 close/destroy/空闲触发\n\t\t// 不产生第二套停机语义, 先到者 (优雅或强制) 定夺。\n\t\tif (finishPromise !== undefined) return finishPromise;\n\t\tfinishPromise = (async () => {\n\t\t\tclosed = true;\n\t\t\tif (idleTimer !== undefined) {\n\t\t\t\tclearTimeout(idleTimer);\n\t\t\t\tidleTimer = undefined;\n\t\t\t}\n\t\t\tif (staleSweepTimer !== undefined) {\n\t\t\t\tclearInterval(staleSweepTimer);\n\t\t\t\tstaleSweepTimer = undefined;\n\t\t\t}\n\t\t\t// 停止接受新连接; 优雅模式先排空串行队列 (在途响应写回), 再断开全部\n\t\t\t// 连接 (客户端 pending 结构化失败 — 设计 §4); 强制模式立即断连。\n\t\t\tconst stopped = new Promise<void>((resolve) => server.close(() => resolve()));\n\t\t\tif (drain) await queueTail.catch(() => undefined);\n\t\t\tfor (const socket of sockets) {\n\t\t\t\t// 优雅路径用 end() (FIN): 内核把在途回程响应刷完再关, 客户端 pending\n\t\t\t\t// 先收到结果; 强制路径 destroy() 立即丢弃 (客户端 pending 结构化失败)。\n\t\t\t\tif (drain) socket.end();\n\t\t\t\telse socket.destroy();\n\t\t\t}\n\t\t\tsockets.clear();\n\t\t\tsocketStates.clear();\n\t\t\tawait stopped;\n\t\t\tif (drain) {\n\t\t\t\ttry {\n\t\t\t\t\tawait options.backend.vectorIndex.close();\n\t\t\t\t} catch (error) {\n\t\t\t\t\toptions.onError?.(\n\t\t\t\t\t\terror instanceof Error ? error : new Error(String(error)),\n\t\t\t\t\t\t`inference-server:close:${reason}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tcloseResolve?.();\n\t\t})();\n\t\treturn finishPromise;\n\t};\n\n\toptions.signal?.addEventListener(\n\t\t\"abort\",\n\t\t() => {\n\t\t\tvoid finishClose(\"signal\", true);\n\t\t},\n\t\t{ once: true },\n\t);\n\n\treturn new Promise<MemoryInferenceServerV1>((resolve, reject) => {\n\t\tconst onListenError = (error: Error) => {\n\t\t\tserver.close();\n\t\t\treject(error);\n\t\t};\n\t\tserver.once(\"error\", onListenError);\n\t\tserver.listen(options.port ?? MEMORY_INFERENCE_DEFAULT_PORT, host, () => {\n\t\t\tserver.off(\"error\", onListenError);\n\t\t\tconst address = server.address();\n\t\t\tif (address === null || typeof address === \"string\") {\n\t\t\t\treject(new Error(\"inference server failed to bind a TCP port\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tserver.on(\"error\", (error) => {\n\t\t\t\toptions.onError?.(error, \"inference-server:server\");\n\t\t\t});\n\t\t\tconst api: MemoryInferenceServerV1 = {\n\t\t\t\tport: address.port,\n\t\t\t\thost,\n\t\t\t\tclose: () => finishClose(\"explicit\", true),\n\t\t\t\tdestroy: () => finishClose(\"destroy\", false),\n\t\t\t\tclosed: closedPromise,\n\t\t\t};\n\t\t\tresolve(api);\n\t\t\t// 已在无连接状态启动 (例如 signal 先行 abort) 时立刻评估空闲退出。\n\t\t\tmaybeScheduleIdleExit();\n\t\t\tstartStaleSweep();\n\t\t});\n\t});\n}\n"]}

package/dist/memory/inference-server.js

@@ -0,0 +1,395 @@
+/**
+ * 记忆共享推理服务 — 服务端 (记忆共享推理服务设计 §3.1/§3.4/§3.5)。
+ *
+ * 常驻 sidecar 的服务端面: 持有唯一的推理后端 (embedProvider/reranker/
+ * vectorIndex — 生产装配为真实 transformers + LanceDB, 测试注入 deterministic
+ * mock), 经 TCP loopback 服务 `inference-protocol.ts` 的消息面。
+ *
+ * 串行化 (设计 §3.4): 所有请求经单条 promise 链按到达序执行 — LanceDB 表
+ * 创建与 ONNX 管线未声明并发安全, 单用户量级下串行的吞吐足够, 正确性优先
+ * (同一理由: 每进程一个 vectorQueue 的既有先例)。
+ *
+ * 逐请求看门狗 (2026-10-06, 设计 §3.4): 后端派发超过 requestWatchdogMs
+ * (缺省 MEMORY_INFERENCE_REQUEST_WATCHDOG_MS) 即对该请求返回结构化
+ * backend_error, 串行队列恢复推进 — 后端永不落定时 (如 ONNX 挂起) 其余请求
+ * 不再排队等死。诚实约束: JS 侧超时不中断底层原生调用 (ONNX 线程仍占住),
+ * 语义是"队列恢复推进、后续请求可用", 不是后端取消。
+ *
+ * 生命周期 (设计 §3.5): 空闲自杀 — 无活跃连接且无在途请求持续 idleTimeoutMs 后
+ * 优雅关闭 (端口让出, 下一个使用者重新拉起); 新连接取消计时。活跃 = 有在途请求,
+ * 或最近收到帧距今未超过连接活跃度阈值 (connectionStaleMs): 挂起不退的客户端
+ * (逻辑死、socket 活) 不再把空闲退出永久按住, 由周期清扫重估。close() 供
+ * 进程入口与测试显式停机。
+ */
+import { createServer } from "node:net";
+import { FrameDecoder } from "@agent-forge/protocol";
+import { decodeInferenceMessage, encodeInferenceMessage, MEMORY_INFERENCE_DEFAULT_HOST, MEMORY_INFERENCE_DEFAULT_PORT, MEMORY_INFERENCE_PROTOCOL_VERSION, } from "./inference-protocol.js";
+/**
+ * 逐请求看门狗阈值出厂默认 (2026-10-06): 大于客户端请求超时 (装配缝 60s /
+ * 客户端缺省 10s) — 正常慢操作先被客户端放弃, 服务端不打断。诚实约束: JS 侧
+ * 超时不中断底层原生调用 (ONNX 线程仍占住资源), 语义是"串行队列恢复推进、
+ * 后续请求可用", 不是后端取消。
+ */
+export const MEMORY_INFERENCE_REQUEST_WATCHDOG_MS = 120_000;
+/**
+ * 连接活跃度阈值出厂默认 (2026-10-07, codex remote-control 同款先例): 自最近
+ * 收到帧起超过该时长且无在途请求的连接视为陈旧, 不再阻止空闲退出 — 挂起不退
+ * 的客户端 (逻辑死、socket 活) 不会把服务模型永久按驻内存。无协议面新增:
+ * 活跃度由服务端按帧到达自行观测, 客户端零改动。
+ */
+export const MEMORY_INFERENCE_CONNECTION_STALE_MS = 10 * 60 * 1000;
+/** 陈旧连接清扫周期上限; 实际取 min(本值, 阈值/2), 测试注入短阈值即得短周期。 */
+const CONNECTION_STALE_SWEEP_MAX_MS = 30_000;
+export function createMemoryInferenceServer(options) {
+    const host = options.host ?? MEMORY_INFERENCE_DEFAULT_HOST;
+    const idleTimeoutMs = options.idleTimeoutMs ?? 0;
+    const connectionStaleMs = options.connectionStaleMs ?? MEMORY_INFERENCE_CONNECTION_STALE_MS;
+    const requestWatchdogMs = options.requestWatchdogMs ?? MEMORY_INFERENCE_REQUEST_WATCHDOG_MS;
+    let idleTimer;
+    const sockets = new Set();
+    // 连接活跃度 (2026-10-07): 每连接最近帧到达时刻 + 在途请求数。活跃 = 有在途
+    // 请求 (帧可能早于陈旧阈值 — 串行队列排队/后端慢不算挂起), 或最近帧未超阈。
+    const socketStates = new Map();
+    let closed = false;
+    let closeResolve;
+    const closedPromise = new Promise((resolve) => {
+        closeResolve = resolve;
+    });
+    // 全局串行队列: 所有连接的全部请求按到达序执行 (设计 §3.4)。
+    let queueTail = Promise.resolve();
+    const enqueue = (operation) => {
+        const next = queueTail.then(operation, operation);
+        queueTail = next.catch(() => undefined);
+        return next;
+    };
+    // 逐请求看门狗 (2026-10-06): 包住单次后端派发, 超时即返回结构化 backend_error,
+    // 让串行队列的当前位置落定 — 后端 promise 永不落定时 (如 ONNX 挂起) 后续请求
+    // 不再排队等死。诚实约束: 超时只是不再等待, 底层原生调用无法被中断 (ONNX
+    // 线程仍占住资源), 语义是"队列恢复推进、后续请求可用", 不是后端取消; 输掉
+    // 竞速的 handleRequest 在后台落定, 其迟到结果被丢弃 (连接可能已亡, write
+    // 错误走 socket error 处理)。
+    const withRequestWatchdog = (request, operation) => {
+        let watchdog;
+        const expired = new Promise((resolve) => {
+            watchdog = setTimeout(() => {
+                resolve({
+                    kind: "error",
+                    requestId: request.requestId,
+                    code: "backend_error",
+                    message: `memory inference backend timed out after ${requestWatchdogMs}ms (request kind=${request.kind})`,
+                });
+            }, requestWatchdogMs);
+            watchdog.unref?.();
+        });
+        return Promise.race([operation, expired]).finally(() => clearTimeout(watchdog));
+    };
+    const server = createServer((socket) => {
+        sockets.add(socket);
+        socketStates.set(socket, { lastFrameAt: Date.now(), pendingRequests: 0 });
+        if (idleTimer !== undefined) {
+            clearTimeout(idleTimer);
+            idleTimer = undefined;
+        }
+        const decoder = new FrameDecoder();
+        // 响应写回 (2026-10-06): 超过 16MB 帧/CBOR 上限的响应 (如 full 档大包
+        // embed) 无法原样编码, 编码抛错若不接住会被 enqueue 的队列兜底 catch 吞
+        // 掉 — 客户端吃满请求超时且根因不可见。回小体量结构化错误帧让客户端
+        // 立刻拿到根因并收缩批量; 错误帧自身再失败只能断连 (socket 已不可写)。
+        const writeResponse = (response, endAfter) => {
+            let payload = response;
+            let bytes;
+            try {
+                bytes = encodeInferenceMessage(payload);
+            }
+            catch (encodeError) {
+                options.onError?.(encodeError instanceof Error ? encodeError : new Error(String(encodeError)), "inference-server:encode");
+                try {
+                    payload = {
+                        kind: "error",
+                        requestId: response.requestId,
+                        code: "backend_error",
+                        message: `memory inference response exceeds the wire frame limit; shrink the batch (${encodeError instanceof Error ? encodeError.message : String(encodeError)})`,
+                    };
+                    bytes = encodeInferenceMessage(payload);
+                }
+                catch {
+                    socket.destroy();
+                    return;
+                }
+            }
+            socket.write(bytes, endAfter ? () => socket.end() : undefined);
+        };
+        socket.on("data", (chunk) => {
+            // 任何字节到达都是活跃度证据 (坏帧连接随后即被断开, 无所谓)。
+            const socketState = socketStates.get(socket);
+            if (socketState !== undefined)
+                socketState.lastFrameAt = Date.now();
+            // 帧层异常必须捕获 (复审 P2-1): 声明长度超限的帧在 data 监听器抛
+            // FrameError 即 uncaughtException — 坏帧/合法超大帧可干死服务进程。
+            // 先例: subagent/stdio-channel.ts 同款处理。
+            let frames;
+            try {
+                frames = decoder.push(new Uint8Array(chunk));
+            }
+            catch (error) {
+                options.onError?.(error instanceof Error ? error : new Error(String(error)), "inference-server:frame");
+                socket.destroy();
+                return;
+            }
+            for (const frame of frames) {
+                if (frame.byteLength === 0)
+                    continue;
+                let request;
+                try {
+                    request = decodeInferenceMessage(frame);
+                }
+                catch (error) {
+                    options.onError?.(error instanceof Error ? error : new Error(String(error)), "inference-server:decode");
+                    socket.end();
+                    return;
+                }
+                if (socketState !== undefined)
+                    socketState.pendingRequests += 1;
+                void enqueue(() => withRequestWatchdog(request, handleRequest(request)).then((response) => {
+                    // 优雅停机期间在途响应仍写回 (close 先排空队列再断连);
+                    // socket 已亡时 write 错误走 socket error 处理。
+                    if (response.kind === "error" && response.code === "protocol_version") {
+                        writeResponse(response, true);
+                        return;
+                    }
+                    writeResponse(response, false);
+                }, () => undefined)).finally(() => {
+                    if (socketState !== undefined)
+                        socketState.pendingRequests -= 1;
+                });
+            }
+        });
+        const drop = () => {
+            socket.destroy();
+        };
+        socket.on("error", (error) => {
+            options.onError?.(error, "inference-server:socket");
+            drop();
+        });
+        socket.on("close", () => {
+            sockets.delete(socket);
+            socketStates.delete(socket);
+            maybeScheduleIdleExit();
+        });
+    });
+    /**
+     * 活跃连接数: 有在途请求, 或最近帧距现在未超过活跃度阈值的连接。
+     * connectionStaleMs <= 0 时退化为全部连接 (原语义)。
+     */
+    const activeConnectionCount = () => {
+        if (connectionStaleMs <= 0)
+            return sockets.size;
+        const nowMs = Date.now();
+        let active = 0;
+        for (const socket of sockets) {
+            const state = socketStates.get(socket);
+            if (state === undefined)
+                continue;
+            if (state.pendingRequests > 0 || nowMs - state.lastFrameAt < connectionStaleMs)
+                active += 1;
+        }
+        return active;
+    };
+    const handleRequest = async (request) => {
+        try {
+            switch (request.kind) {
+                case "hello": {
+                    if (request.protocolVersion !== MEMORY_INFERENCE_PROTOCOL_VERSION) {
+                        return {
+                            kind: "error",
+                            requestId: request.requestId,
+                            code: "protocol_version",
+                            message: `inference protocol version mismatch: server=${MEMORY_INFERENCE_PROTOCOL_VERSION} client=${request.protocolVersion}`,
+                        };
+                    }
+                    // agentDir 身份上报 (2026-10-06 串线修复): 有则带 (生产经
+                    // runMemoryInferenceService 传入), 无则不带 — 直连本工厂的旧
+                    // 测试缝与升级过渡期的旧版本服务进程保持 wire 兼容, 会话装配
+                    // 按字段缺失拒绝 (设计 §3.2)。
+                    const helloBase = {
+                        protocolVersion: MEMORY_INFERENCE_PROTOCOL_VERSION,
+                        embeddingModelId: options.backend.embedProvider.modelId,
+                        dimensions: options.backend.embedProvider.dimensions,
+                        rerankerModelId: options.backend.reranker?.modelId ?? null,
+                    };
+                    return {
+                        kind: "ok",
+                        requestId: request.requestId,
+                        result: options.agentDir === undefined
+                            ? helloBase
+                            : { ...helloBase, agentDir: options.agentDir },
+                    };
+                }
+                case "embed": {
+                    const vectors = await options.backend.embedProvider.embed(request.texts);
+                    return { kind: "ok", requestId: request.requestId, result: { vectors } };
+                }
+                case "rerank": {
+                    if (options.backend.reranker === undefined) {
+                        return {
+                            kind: "error",
+                            requestId: request.requestId,
+                            code: "backend_error",
+                            message: "inference server has no reranker",
+                        };
+                    }
+                    const scores = await options.backend.reranker.rerank(request.query, request.docs);
+                    return { kind: "ok", requestId: request.requestId, result: { scores } };
+                }
+                case "queryKnn": {
+                    const hits = await options.backend.vectorIndex.queryKnn(request.vector, request.query);
+                    return { kind: "ok", requestId: request.requestId, result: { hits } };
+                }
+                case "queryFts": {
+                    const hits = await options.backend.vectorIndex.queryFts(request.queryText, request.query);
+                    return { kind: "ok", requestId: request.requestId, result: { hits } };
+                }
+                case "upsert": {
+                    await options.backend.vectorIndex.upsert(request.entries);
+                    return { kind: "ok", requestId: request.requestId, result: { pong: true } };
+                }
+                case "remove": {
+                    await options.backend.vectorIndex.remove(request.memoryIds);
+                    return { kind: "ok", requestId: request.requestId, result: { pong: true } };
+                }
+                case "listMemoryIds": {
+                    const ids = await options.backend.vectorIndex.listMemoryIds();
+                    return { kind: "ok", requestId: request.requestId, result: { memoryIds: [...ids] } };
+                }
+                case "count": {
+                    const count = await options.backend.vectorIndex.count();
+                    return { kind: "ok", requestId: request.requestId, result: { count } };
+                }
+                case "getStoredModelId": {
+                    const modelId = await options.backend.vectorIndex.getStoredModelId();
+                    return { kind: "ok", requestId: request.requestId, result: { modelId: modelId ?? null } };
+                }
+                case "ping":
+                    return { kind: "ok", requestId: request.requestId, result: { pong: true } };
+                default:
+                    return {
+                        kind: "error",
+                        requestId: request.requestId,
+                        code: "bad_request",
+                        message: `unknown inference request kind: ${request.kind}`,
+                    };
+            }
+        }
+        catch (error) {
+            return {
+                kind: "error",
+                requestId: request.requestId,
+                code: "backend_error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+    };
+    const maybeScheduleIdleExit = () => {
+        if (closed || idleTimeoutMs <= 0 || activeConnectionCount() > 0 || idleTimer !== undefined)
+            return;
+        idleTimer = setTimeout(() => {
+            idleTimer = undefined;
+            if (activeConnectionCount() > 0 || closed)
+                return;
+            void finishClose("idle", true);
+        }, idleTimeoutMs);
+        idleTimer.unref?.();
+    };
+    // 陈旧连接清扫 (2026-10-07): 活跃→陈旧的转变没有事件 (挂起客户端不发帧也
+    // 不断连), 靠周期扫描重估空闲退出。周期取 min(30s, 阈值/2) — 生产 30s,
+    // 测试注入短阈值即得短周期。仅在空闲退出与活跃度阈值都启用时运转。
+    let staleSweepTimer;
+    const startStaleSweep = () => {
+        if (closed || idleTimeoutMs <= 0 || connectionStaleMs <= 0 || staleSweepTimer !== undefined) {
+            return;
+        }
+        const sweepIntervalMs = Math.min(CONNECTION_STALE_SWEEP_MAX_MS, Math.max(1, Math.floor(connectionStaleMs / 2)));
+        staleSweepTimer = setInterval(() => {
+            if (!closed)
+                maybeScheduleIdleExit();
+        }, sweepIntervalMs);
+        staleSweepTimer.unref?.();
+    };
+    let finishPromise;
+    const finishClose = (reason, drain) => {
+        // 并发调用统一返回同一次停机 (复审 P3-5): 后到的 close/destroy/空闲触发
+        // 不产生第二套停机语义, 先到者 (优雅或强制) 定夺。
+        if (finishPromise !== undefined)
+            return finishPromise;
+        finishPromise = (async () => {
+            closed = true;
+            if (idleTimer !== undefined) {
+                clearTimeout(idleTimer);
+                idleTimer = undefined;
+            }
+            if (staleSweepTimer !== undefined) {
+                clearInterval(staleSweepTimer);
+                staleSweepTimer = undefined;
+            }
+            // 停止接受新连接; 优雅模式先排空串行队列 (在途响应写回), 再断开全部
+            // 连接 (客户端 pending 结构化失败 — 设计 §4); 强制模式立即断连。
+            const stopped = new Promise((resolve) => server.close(() => resolve()));
+            if (drain)
+                await queueTail.catch(() => undefined);
+            for (const socket of sockets) {
+                // 优雅路径用 end() (FIN): 内核把在途回程响应刷完再关, 客户端 pending
+                // 先收到结果; 强制路径 destroy() 立即丢弃 (客户端 pending 结构化失败)。
+                if (drain)
+                    socket.end();
+                else
+                    socket.destroy();
+            }
+            sockets.clear();
+            socketStates.clear();
+            await stopped;
+            if (drain) {
+                try {
+                    await options.backend.vectorIndex.close();
+                }
+                catch (error) {
+                    options.onError?.(error instanceof Error ? error : new Error(String(error)), `inference-server:close:${reason}`);
+                }
+            }
+            closeResolve?.();
+        })();
+        return finishPromise;
+    };
+    options.signal?.addEventListener("abort", () => {
+        void finishClose("signal", true);
+    }, { once: true });
+    return new Promise((resolve, reject) => {
+        const onListenError = (error) => {
+            server.close();
+            reject(error);
+        };
+        server.once("error", onListenError);
+        server.listen(options.port ?? MEMORY_INFERENCE_DEFAULT_PORT, host, () => {
+            server.off("error", onListenError);
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                reject(new Error("inference server failed to bind a TCP port"));
+                return;
+            }
+            server.on("error", (error) => {
+                options.onError?.(error, "inference-server:server");
+            });
+            const api = {
+                port: address.port,
+                host,
+                close: () => finishClose("explicit", true),
+                destroy: () => finishClose("destroy", false),
+                closed: closedPromise,
+            };
+            resolve(api);
+            // 已在无连接状态启动 (例如 signal 先行 abort) 时立刻评估空闲退出。
+            maybeScheduleIdleExit();
+            startStaleSweep();
+        });
+    });
+}
+//# sourceMappingURL=inference-server.js.map

package/dist/memory/inference-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inference-server.js","sourceRoot":"","sources":["../../src/memory/inference-server.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * 记忆共享推理服务 — 服务端 (记忆共享推理服务设计 §3.1/§3.4/§3.5)。\n *\n * 常驻 sidecar 的服务端面: 持有唯一的推理后端 (embedProvider/reranker/\n * vectorIndex — 生产装配为真实 transformers + LanceDB, 测试注入 deterministic\n * mock), 经 TCP loopback 服务 `inference-protocol.ts` 的消息面。\n *\n * 串行化 (设计 §3.4): 所有请求经单条 promise 链按到达序执行 — LanceDB 表\n * 创建与 ONNX 管线未声明并发安全, 单用户量级下串行的吞吐足够, 正确性优先\n * (同一理由: 每进程一个 vectorQueue 的既有先例)。\n *\n * 逐请求看门狗 (2026-10-06, 设计 §3.4): 后端派发超过 requestWatchdogMs\n * (缺省 MEMORY_INFERENCE_REQUEST_WATCHDOG_MS) 即对该请求返回结构化\n * backend_error, 串行队列恢复推进 — 后端永不落定时 (如 ONNX 挂起) 其余请求\n * 不再排队等死。诚实约束: JS 侧超时不中断底层原生调用 (ONNX 线程仍占住),\n * 语义是\"队列恢复推进、后续请求可用\", 不是后端取消。\n *\n * 生命周期 (设计 §3.5): 空闲自杀 — 无活跃连接且无在途请求持续 idleTimeoutMs 后\n * 优雅关闭 (端口让出, 下一个使用者重新拉起); 新连接取消计时。活跃 = 有在途请求,\n * 或最近收到帧距今未超过连接活跃度阈值 (connectionStaleMs): 挂起不退的客户端\n * (逻辑死、socket 活) 不再把空闲退出永久按住, 由周期清扫重估。close() 供\n * 进程入口与测试显式停机。\n */\nimport { createServer, type Server, type Socket } from \"node:net\";\nimport { FrameDecoder } from \"@agent-forge/protocol\";\nimport type { MemoryEmbeddingProviderV1 } from \"./embedding-provider.ts\";\nimport type { MemoryRerankerV1 } from \"./embedding-reranker.ts\";\nimport {\n\tdecodeInferenceMessage,\n\tencodeInferenceMessage,\n\tMEMORY_INFERENCE_DEFAULT_HOST,\n\tMEMORY_INFERENCE_DEFAULT_PORT,\n\tMEMORY_INFERENCE_PROTOCOL_VERSION,\n\ttype MemoryInferenceHelloResultV1,\n\ttype MemoryInferenceRequestV1,\n\ttype MemoryInferenceResponseV1,\n} from \"./inference-protocol.ts\";\nimport type { MemoryVectorIndexV1 } from \"./vector-index.ts\";\n\n/**\n * 逐请求看门狗阈值出厂默认 (2026-10-06): 大于客户端请求超时 (装配缝 60s /\n * 客户端缺省 10s) — 正常慢操作先被客户端放弃, 服务端不打断。诚实约束: JS 侧\n * 超时不中断底层原生调用 (ONNX 线程仍占住资源), 语义是\"串行队列恢复推进、\n * 后续请求可用\", 不是后端取消。\n */\nexport const MEMORY_INFERENCE_REQUEST_WATCHDOG_MS = 120_000;\n\n/**\n * 连接活跃度阈值出厂默认 (2026-10-07, codex remote-control 同款先例): 自最近\n * 收到帧起超过该时长且无在途请求的连接视为陈旧, 不再阻止空闲退出 — 挂起不退\n * 的客户端 (逻辑死、socket 活) 不会把服务模型永久按驻内存。无协议面新增:\n * 活跃度由服务端按帧到达自行观测, 客户端零改动。\n */\nexport const MEMORY_INFERENCE_CONNECTION_STALE_MS = 10 * 60 * 1000;\n\n/** 陈旧连接清扫周期上限; 实际取 min(本值, 阈值/2), 测试注入短阈值即得短周期。 */\nconst CONNECTION_STALE_SWEEP_MAX_MS = 30_000;\n\n/** 服务端持有的唯一推理后端 (生产 = 真实装配; 测试 = deterministic mock)。 */\nexport interface MemoryInferenceBackendV1 {\n\treadonly embedProvider: MemoryEmbeddingProviderV1;\n\treadonly reranker?: MemoryRerankerV1;\n\treadonly vectorIndex: MemoryVectorIndexV1;\n}\n\nexport interface MemoryInferenceServerV1 {\n\t/** 实际绑定端口 (port: 0 时为 OS 分配值 — 测试用; 生产固定端口即单例互斥)。 */\n\treadonly port: number;\n\treadonly host: string;\n\t/**\n\t * 优雅停机: 停止监听 → 排空串行队列 (在途响应写回) → 断开全部连接 → 关闭\n\t * 索引句柄。幂等。\n\t */\n\tclose(): Promise<void>;\n\t/**\n\t * 强制停机 (模拟进程死亡/紧急退出): 立即断开全部连接与在途请求 (客户端\n\t * pending 全部结构化失败 — 设计 §4), 不等待队列排空。\n\t */\n\tdestroy(): Promise<void>;\n\t/** 服务完全关闭 (显式或空闲自杀) 后 resolve。 */\n\treadonly closed: Promise<void>;\n}\n\nexport interface MemoryInferenceServerOptions {\n\treadonly backend: MemoryInferenceBackendV1;\n\t/** 缺省 MEMORY_INFERENCE_DEFAULT_PORT; 0 = OS 分配 (测试)。同端口二次绑定 reject (单例互斥)。 */\n\treadonly port?: number;\n\treadonly host?: string;\n\t/** 空闲自杀阈值 (无活跃连接且无在途请求)。缺省 0 = 不启用。出厂默认值登记产品默认值清单。 */\n\treadonly idleTimeoutMs?: number;\n\t/**\n\t * 连接活跃度阈值 (2026-10-07): 见 MEMORY_INFERENCE_CONNECTION_STALE_MS。\n\t * 缺省 10 分钟; 0 = 关闭 (任何连接都阻止空闲退出 — 原语义)。\n\t */\n\treadonly connectionStaleMs?: number;\n\t/**\n\t * 服务进程的 agent-dir 身份 (2026-10-06 串线修复): hello 握手回报给客户端,\n\t * 会话装配据此拒绝跨 agent-dir 串线。缺省不上报 (旧版本 wire 兼容, 装配校验\n\t * 按缺失拒绝); 生产服务经 runMemoryInferenceService 传入。\n\t */\n\treadonly agentDir?: string;\n\t/**\n\t * 逐请求看门狗阈值: 后端派发超过该时长即对该请求返回结构化 backend_error,\n\t * 串行队列继续推进 (不中断底层原生调用 — 见\n\t * MEMORY_INFERENCE_REQUEST_WATCHDOG_MS 注释)。缺省 120s; 测试注入小值。\n\t */\n\treadonly requestWatchdogMs?: number;\n\treadonly signal?: AbortSignal;\n\t/** 结构化错误面 (日志/诊断); 不抛出 — 服务端错误一律转为 error 响应或告警。 */\n\treadonly onError?: (error: Error, context: string) => void;\n}\n\nexport function createMemoryInferenceServer(options: MemoryInferenceServerOptions): Promise<MemoryInferenceServerV1> {\n\tconst host = options.host ?? MEMORY_INFERENCE_DEFAULT_HOST;\n\tconst idleTimeoutMs = options.idleTimeoutMs ?? 0;\n\tconst connectionStaleMs = options.connectionStaleMs ?? MEMORY_INFERENCE_CONNECTION_STALE_MS;\n\tconst requestWatchdogMs = options.requestWatchdogMs ?? MEMORY_INFERENCE_REQUEST_WATCHDOG_MS;\n\tlet idleTimer: NodeJS.Timeout | undefined;\n\tconst sockets = new Set<Socket>();\n\t// 连接活跃度 (2026-10-07): 每连接最近帧到达时刻 + 在途请求数。活跃 = 有在途\n\t// 请求 (帧可能早于陈旧阈值 — 串行队列排队/后端慢不算挂起), 或最近帧未超阈。\n\tconst socketStates = new Map<Socket, { lastFrameAt: number; pendingRequests: number }>();\n\tlet closed = false;\n\tlet closeResolve: (() => void) | undefined;\n\tconst closedPromise = new Promise<void>((resolve) => {\n\t\tcloseResolve = resolve;\n\t});\n\t// 全局串行队列: 所有连接的全部请求按到达序执行 (设计 §3.4)。\n\tlet queueTail: Promise<void> = Promise.resolve();\n\tconst enqueue = (operation: () => Promise<void>): Promise<void> => {\n\t\tconst next = queueTail.then(operation, operation);\n\t\tqueueTail = next.catch(() => undefined);\n\t\treturn next;\n\t};\n\t// 逐请求看门狗 (2026-10-06): 包住单次后端派发, 超时即返回结构化 backend_error,\n\t// 让串行队列的当前位置落定 — 后端 promise 永不落定时 (如 ONNX 挂起) 后续请求\n\t// 不再排队等死。诚实约束: 超时只是不再等待, 底层原生调用无法被中断 (ONNX\n\t// 线程仍占住资源), 语义是\"队列恢复推进、后续请求可用\", 不是后端取消; 输掉\n\t// 竞速的 handleRequest 在后台落定, 其迟到结果被丢弃 (连接可能已亡, write\n\t// 错误走 socket error 处理)。\n\tconst withRequestWatchdog = (\n\t\trequest: MemoryInferenceRequestV1,\n\t\toperation: Promise<MemoryInferenceResponseV1>,\n\t): Promise<MemoryInferenceResponseV1> => {\n\t\tlet watchdog: NodeJS.Timeout | undefined;\n\t\tconst expired = new Promise<MemoryInferenceResponseV1>((resolve) => {\n\t\t\twatchdog = setTimeout(() => {\n\t\t\t\tresolve({\n\t\t\t\t\tkind: \"error\",\n\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\tmessage: `memory inference backend timed out after ${requestWatchdogMs}ms (request kind=${request.kind})`,\n\t\t\t\t});\n\t\t\t}, requestWatchdogMs);\n\t\t\twatchdog.unref?.();\n\t\t});\n\t\treturn Promise.race([operation, expired]).finally(() => clearTimeout(watchdog));\n\t};\n\n\tconst server: Server = createServer((socket: Socket) => {\n\t\tsockets.add(socket);\n\t\tsocketStates.set(socket, { lastFrameAt: Date.now(), pendingRequests: 0 });\n\t\tif (idleTimer !== undefined) {\n\t\t\tclearTimeout(idleTimer);\n\t\t\tidleTimer = undefined;\n\t\t}\n\t\tconst decoder = new FrameDecoder();\n\t\t// 响应写回 (2026-10-06): 超过 16MB 帧/CBOR 上限的响应 (如 full 档大包\n\t\t// embed) 无法原样编码, 编码抛错若不接住会被 enqueue 的队列兜底 catch 吞\n\t\t// 掉 — 客户端吃满请求超时且根因不可见。回小体量结构化错误帧让客户端\n\t\t// 立刻拿到根因并收缩批量; 错误帧自身再失败只能断连 (socket 已不可写)。\n\t\tconst writeResponse = (response: MemoryInferenceResponseV1, endAfter: boolean): void => {\n\t\t\tlet payload = response;\n\t\t\tlet bytes: Uint8Array;\n\t\t\ttry {\n\t\t\t\tbytes = encodeInferenceMessage(payload);\n\t\t\t} catch (encodeError) {\n\t\t\t\toptions.onError?.(\n\t\t\t\t\tencodeError instanceof Error ? encodeError : new Error(String(encodeError)),\n\t\t\t\t\t\"inference-server:encode\",\n\t\t\t\t);\n\t\t\t\ttry {\n\t\t\t\t\tpayload = {\n\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\trequestId: response.requestId,\n\t\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\t\tmessage: `memory inference response exceeds the wire frame limit; shrink the batch (${\n\t\t\t\t\t\t\tencodeError instanceof Error ? encodeError.message : String(encodeError)\n\t\t\t\t\t\t})`,\n\t\t\t\t\t};\n\t\t\t\t\tbytes = encodeInferenceMessage(payload);\n\t\t\t\t} catch {\n\t\t\t\t\tsocket.destroy();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t}\n\t\t\tsocket.write(bytes, endAfter ? () => socket.end() : undefined);\n\t\t};\n\t\tsocket.on(\"data\", (chunk: Buffer) => {\n\t\t\t// 任何字节到达都是活跃度证据 (坏帧连接随后即被断开, 无所谓)。\n\t\t\tconst socketState = socketStates.get(socket);\n\t\t\tif (socketState !== undefined) socketState.lastFrameAt = Date.now();\n\t\t\t// 帧层异常必须捕获 (复审 P2-1): 声明长度超限的帧在 data 监听器抛\n\t\t\t// FrameError 即 uncaughtException — 坏帧/合法超大帧可干死服务进程。\n\t\t\t// 先例: subagent/stdio-channel.ts 同款处理。\n\t\t\tlet frames: Uint8Array[];\n\t\t\ttry {\n\t\t\t\tframes = decoder.push(new Uint8Array(chunk));\n\t\t\t} catch (error) {\n\t\t\t\toptions.onError?.(error instanceof Error ? error : new Error(String(error)), \"inference-server:frame\");\n\t\t\t\tsocket.destroy();\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tfor (const frame of frames) {\n\t\t\t\tif (frame.byteLength === 0) continue;\n\t\t\t\tlet request: MemoryInferenceRequestV1;\n\t\t\t\ttry {\n\t\t\t\t\trequest = decodeInferenceMessage(frame) as MemoryInferenceRequestV1;\n\t\t\t\t} catch (error) {\n\t\t\t\t\toptions.onError?.(error instanceof Error ? error : new Error(String(error)), \"inference-server:decode\");\n\t\t\t\t\tsocket.end();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tif (socketState !== undefined) socketState.pendingRequests += 1;\n\t\t\t\tvoid enqueue(() =>\n\t\t\t\t\twithRequestWatchdog(request, handleRequest(request)).then(\n\t\t\t\t\t\t(response) => {\n\t\t\t\t\t\t\t// 优雅停机期间在途响应仍写回 (close 先排空队列再断连);\n\t\t\t\t\t\t\t// socket 已亡时 write 错误走 socket error 处理。\n\t\t\t\t\t\t\tif (response.kind === \"error\" && response.code === \"protocol_version\") {\n\t\t\t\t\t\t\t\twriteResponse(response, true);\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\twriteResponse(response, false);\n\t\t\t\t\t\t},\n\t\t\t\t\t\t() => undefined,\n\t\t\t\t\t),\n\t\t\t\t).finally(() => {\n\t\t\t\t\tif (socketState !== undefined) socketState.pendingRequests -= 1;\n\t\t\t\t});\n\t\t\t}\n\t\t});\n\t\tconst drop = () => {\n\t\t\tsocket.destroy();\n\t\t};\n\t\tsocket.on(\"error\", (error) => {\n\t\t\toptions.onError?.(error, \"inference-server:socket\");\n\t\t\tdrop();\n\t\t});\n\t\tsocket.on(\"close\", () => {\n\t\t\tsockets.delete(socket);\n\t\t\tsocketStates.delete(socket);\n\t\t\tmaybeScheduleIdleExit();\n\t\t});\n\t});\n\n\t/**\n\t * 活跃连接数: 有在途请求, 或最近帧距现在未超过活跃度阈值的连接。\n\t * connectionStaleMs <= 0 时退化为全部连接 (原语义)。\n\t */\n\tconst activeConnectionCount = (): number => {\n\t\tif (connectionStaleMs <= 0) return sockets.size;\n\t\tconst nowMs = Date.now();\n\t\tlet active = 0;\n\t\tfor (const socket of sockets) {\n\t\t\tconst state = socketStates.get(socket);\n\t\t\tif (state === undefined) continue;\n\t\t\tif (state.pendingRequests > 0 || nowMs - state.lastFrameAt < connectionStaleMs) active += 1;\n\t\t}\n\t\treturn active;\n\t};\n\n\tconst handleRequest = async (request: MemoryInferenceRequestV1): Promise<MemoryInferenceResponseV1> => {\n\t\ttry {\n\t\t\tswitch (request.kind) {\n\t\t\t\tcase \"hello\": {\n\t\t\t\t\tif (request.protocolVersion !== MEMORY_INFERENCE_PROTOCOL_VERSION) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\t\tcode: \"protocol_version\",\n\t\t\t\t\t\t\tmessage: `inference protocol version mismatch: server=${MEMORY_INFERENCE_PROTOCOL_VERSION} client=${request.protocolVersion}`,\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\t// agentDir 身份上报 (2026-10-06 串线修复): 有则带 (生产经\n\t\t\t\t\t// runMemoryInferenceService 传入), 无则不带 — 直连本工厂的旧\n\t\t\t\t\t// 测试缝与升级过渡期的旧版本服务进程保持 wire 兼容, 会话装配\n\t\t\t\t\t// 按字段缺失拒绝 (设计 §3.2)。\n\t\t\t\t\tconst helloBase = {\n\t\t\t\t\t\tprotocolVersion: MEMORY_INFERENCE_PROTOCOL_VERSION,\n\t\t\t\t\t\tembeddingModelId: options.backend.embedProvider.modelId,\n\t\t\t\t\t\tdimensions: options.backend.embedProvider.dimensions,\n\t\t\t\t\t\trerankerModelId: options.backend.reranker?.modelId ?? null,\n\t\t\t\t\t};\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: \"ok\",\n\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\tresult:\n\t\t\t\t\t\t\toptions.agentDir === undefined\n\t\t\t\t\t\t\t\t? (helloBase as MemoryInferenceHelloResultV1)\n\t\t\t\t\t\t\t\t: { ...helloBase, agentDir: options.agentDir },\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tcase \"embed\": {\n\t\t\t\t\tconst vectors = await options.backend.embedProvider.embed(request.texts);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { vectors } };\n\t\t\t\t}\n\t\t\t\tcase \"rerank\": {\n\t\t\t\t\tif (options.backend.reranker === undefined) {\n\t\t\t\t\t\treturn {\n\t\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\t\trequestId: request.requestId,\n\t\t\t\t\t\t\tcode: \"backend_error\",\n\t\t\t\t\t\t\tmessage: \"inference server has no reranker\",\n\t\t\t\t\t\t};\n\t\t\t\t\t}\n\t\t\t\t\tconst scores = await options.backend.reranker.rerank(request.query, request.docs);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { scores } };\n\t\t\t\t}\n\t\t\t\tcase \"queryKnn\": {\n\t\t\t\t\tconst hits = await options.backend.vectorIndex.queryKnn(request.vector, request.query);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { hits } };\n\t\t\t\t}\n\t\t\t\tcase \"queryFts\": {\n\t\t\t\t\tconst hits = await options.backend.vectorIndex.queryFts(request.queryText, request.query);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { hits } };\n\t\t\t\t}\n\t\t\t\tcase \"upsert\": {\n\t\t\t\t\tawait options.backend.vectorIndex.upsert(request.entries);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\t}\n\t\t\t\tcase \"remove\": {\n\t\t\t\t\tawait options.backend.vectorIndex.remove(request.memoryIds);\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\t}\n\t\t\t\tcase \"listMemoryIds\": {\n\t\t\t\t\tconst ids = await options.backend.vectorIndex.listMemoryIds();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { memoryIds: [...ids] } };\n\t\t\t\t}\n\t\t\t\tcase \"count\": {\n\t\t\t\t\tconst count = await options.backend.vectorIndex.count();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { count } };\n\t\t\t\t}\n\t\t\t\tcase \"getStoredModelId\": {\n\t\t\t\t\tconst modelId = await options.backend.vectorIndex.getStoredModelId();\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { modelId: modelId ?? null } };\n\t\t\t\t}\n\t\t\t\tcase \"ping\":\n\t\t\t\t\treturn { kind: \"ok\", requestId: request.requestId, result: { pong: true } };\n\t\t\t\tdefault:\n\t\t\t\t\treturn {\n\t\t\t\t\t\tkind: \"error\",\n\t\t\t\t\t\trequestId: (request as { requestId: number }).requestId,\n\t\t\t\t\t\tcode: \"bad_request\",\n\t\t\t\t\t\tmessage: `unknown inference request kind: ${(request as { kind: string }).kind}`,\n\t\t\t\t\t};\n\t\t\t}\n\t\t} catch (error) {\n\t\t\treturn {\n\t\t\t\tkind: \"error\",\n\t\t\t\trequestId: request.requestId,\n\t\t\t\tcode: \"backend_error\",\n\t\t\t\tmessage: error instanceof Error ? error.message : String(error),\n\t\t\t};\n\t\t}\n\t};\n\n\tconst maybeScheduleIdleExit = (): void => {\n\t\tif (closed || idleTimeoutMs <= 0 || activeConnectionCount() > 0 || idleTimer !== undefined) return;\n\t\tidleTimer = setTimeout(() => {\n\t\t\tidleTimer = undefined;\n\t\t\tif (activeConnectionCount() > 0 || closed) return;\n\t\t\tvoid finishClose(\"idle\", true);\n\t\t}, idleTimeoutMs);\n\t\tidleTimer.unref?.();\n\t};\n\n\t// 陈旧连接清扫 (2026-10-07): 活跃→陈旧的转变没有事件 (挂起客户端不发帧也\n\t// 不断连), 靠周期扫描重估空闲退出。周期取 min(30s, 阈值/2) — 生产 30s,\n\t// 测试注入短阈值即得短周期。仅在空闲退出与活跃度阈值都启用时运转。\n\tlet staleSweepTimer: NodeJS.Timeout | undefined;\n\tconst startStaleSweep = (): void => {\n\t\tif (closed || idleTimeoutMs <= 0 || connectionStaleMs <= 0 || staleSweepTimer !== undefined) {\n\t\t\treturn;\n\t\t}\n\t\tconst sweepIntervalMs = Math.min(CONNECTION_STALE_SWEEP_MAX_MS, Math.max(1, Math.floor(connectionStaleMs / 2)));\n\t\tstaleSweepTimer = setInterval(() => {\n\t\t\tif (!closed) maybeScheduleIdleExit();\n\t\t}, sweepIntervalMs);\n\t\tstaleSweepTimer.unref?.();\n\t};\n\n\tlet finishPromise: Promise<void> | undefined;\n\tconst finishClose = (reason: string, drain: boolean): Promise<void> => {\n\t\t// 并发调用统一返回同一次停机 (复审 P3-5): 后到的 close/destroy/空闲触发\n\t\t// 不产生第二套停机语义, 先到者 (优雅或强制) 定夺。\n\t\tif (finishPromise !== undefined) return finishPromise;\n\t\tfinishPromise = (async () => {\n\t\t\tclosed = true;\n\t\t\tif (idleTimer !== undefined) {\n\t\t\t\tclearTimeout(idleTimer);\n\t\t\t\tidleTimer = undefined;\n\t\t\t}\n\t\t\tif (staleSweepTimer !== undefined) {\n\t\t\t\tclearInterval(staleSweepTimer);\n\t\t\t\tstaleSweepTimer = undefined;\n\t\t\t}\n\t\t\t// 停止接受新连接; 优雅模式先排空串行队列 (在途响应写回), 再断开全部\n\t\t\t// 连接 (客户端 pending 结构化失败 — 设计 §4); 强制模式立即断连。\n\t\t\tconst stopped = new Promise<void>((resolve) => server.close(() => resolve()));\n\t\t\tif (drain) await queueTail.catch(() => undefined);\n\t\t\tfor (const socket of sockets) {\n\t\t\t\t// 优雅路径用 end() (FIN): 内核把在途回程响应刷完再关, 客户端 pending\n\t\t\t\t// 先收到结果; 强制路径 destroy() 立即丢弃 (客户端 pending 结构化失败)。\n\t\t\t\tif (drain) socket.end();\n\t\t\t\telse socket.destroy();\n\t\t\t}\n\t\t\tsockets.clear();\n\t\t\tsocketStates.clear();\n\t\t\tawait stopped;\n\t\t\tif (drain) {\n\t\t\t\ttry {\n\t\t\t\t\tawait options.backend.vectorIndex.close();\n\t\t\t\t} catch (error) {\n\t\t\t\t\toptions.onError?.(\n\t\t\t\t\t\terror instanceof Error ? error : new Error(String(error)),\n\t\t\t\t\t\t`inference-server:close:${reason}`,\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t}\n\t\t\tcloseResolve?.();\n\t\t})();\n\t\treturn finishPromise;\n\t};\n\n\toptions.signal?.addEventListener(\n\t\t\"abort\",\n\t\t() => {\n\t\t\tvoid finishClose(\"signal\", true);\n\t\t},\n\t\t{ once: true },\n\t);\n\n\treturn new Promise<MemoryInferenceServerV1>((resolve, reject) => {\n\t\tconst onListenError = (error: Error) => {\n\t\t\tserver.close();\n\t\t\treject(error);\n\t\t};\n\t\tserver.once(\"error\", onListenError);\n\t\tserver.listen(options.port ?? MEMORY_INFERENCE_DEFAULT_PORT, host, () => {\n\t\t\tserver.off(\"error\", onListenError);\n\t\t\tconst address = server.address();\n\t\t\tif (address === null || typeof address === \"string\") {\n\t\t\t\treject(new Error(\"inference server failed to bind a TCP port\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tserver.on(\"error\", (error) => {\n\t\t\t\toptions.onError?.(error, \"inference-server:server\");\n\t\t\t});\n\t\t\tconst api: MemoryInferenceServerV1 = {\n\t\t\t\tport: address.port,\n\t\t\t\thost,\n\t\t\t\tclose: () => finishClose(\"explicit\", true),\n\t\t\t\tdestroy: () => finishClose(\"destroy\", false),\n\t\t\t\tclosed: closedPromise,\n\t\t\t};\n\t\t\tresolve(api);\n\t\t\t// 已在无连接状态启动 (例如 signal 先行 abort) 时立刻评估空闲退出。\n\t\t\tmaybeScheduleIdleExit();\n\t\t\tstartStaleSweep();\n\t\t});\n\t});\n}\n"]}

package/dist/memory/inference-service-main.d.ts

@@ -0,0 +1,31 @@
+import type { TransformersEmbeddingLoadImpl } from "./embedding-provider.ts";
+import type { TransformersRerankerLoadImpl } from "./embedding-reranker.ts";
+import { type MemoryInferenceBackendV1, type MemoryInferenceServerV1 } from "./inference-server.ts";
+/** 服务空闲自杀阈值出厂默认 (设计 §3.5; 登记产品默认值清单)。 */
+export declare const MEMORY_INFERENCE_SERVICE_IDLE_TIMEOUT_MS: number;
+export interface MemoryInferenceServiceOptions {
+    readonly agentDir: string;
+    readonly mode: "light" | "full";
+    /** 缺省固定默认端口 (单例互斥); env 覆盖由 createMemoryInferenceServer 端口参数承担。 */
+    readonly port?: number;
+    /** 缺省 MEMORY_INFERENCE_SERVICE_IDLE_TIMEOUT_MS。 */
+    readonly idleTimeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /** 测试缝: 直接给定后端, 跳过真实装配 (模型检查一并跳过)。 */
+    readonly backend?: MemoryInferenceBackendV1;
+    readonly moduleEntryPaths?: {
+        readonly lancedb?: string;
+        readonly transformers?: string;
+    };
+    readonly loadImpls?: {
+        readonly embedding?: TransformersEmbeddingLoadImpl;
+        readonly reranker?: TransformersRerankerLoadImpl;
+    };
+    readonly log?: (line: string) => void;
+}
+/**
+ * 装配并启动共享推理服务。真实装配路径的失败 (模型缺失) 抛结构化错误 —
+ * 进程入口将其转为一行 stderr + 非零退出码; 已监听后返回 server 句柄。
+ */
+export declare function runMemoryInferenceService(options: MemoryInferenceServiceOptions): Promise<MemoryInferenceServerV1>;
+//# sourceMappingURL=inference-service-main.d.ts.map