@njuptlzf/agent-chat-server 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -14,6 +14,11 @@ export interface LoadedProduct {
14
14
  memoryEnabled: boolean;
15
15
  /** Provider id from `agent.memory.provider`; falls back to the platform default. */
16
16
  memoryProviderId: string;
17
+ /**
18
+ * 产品是否声明依赖跨会话用户画像(`agent.memory.requiresSharedProfile`)。
19
+ * 宿主据此在选中的 provider 不支持该能力时告警(C6)。缺省 false。
20
+ */
21
+ requiresSharedProfile: boolean;
17
22
  /**
18
23
  * 外部提供方模块(`agent.memoryProviders`),原样保留声明顺序。
19
24
  * 加载在会话创建前完成——解析与准入扫描要读文件,manifest 解析是同步的。
package/dist/manifest.js CHANGED
@@ -504,6 +504,9 @@ export function loadProduct(dir) {
504
504
  memoryProviderId: typeof manifest.agent.memory === "object" && manifest.agent.memory !== null
505
505
  ? manifest.agent.memory.provider ?? DEFAULT_MEMORY_PROVIDER_ID
506
506
  : DEFAULT_MEMORY_PROVIDER_ID,
507
+ requiresSharedProfile: typeof manifest.agent.memory === "object" && manifest.agent.memory !== null
508
+ ? manifest.agent.memory.requiresSharedProfile === true
509
+ : false,
507
510
  memoryProviderModules: [...(manifest.agent.memoryProviders ?? [])],
508
511
  questionDirs,
509
512
  caseDirs,
@@ -4,23 +4,31 @@
4
4
  * 服务器只认 id,不认实现:换记忆引擎 = 换 manifest 里的 `agent.memory.provider`,
5
5
  * 本文件之外的服务器代码一行不动。
6
6
  *
7
- * 注册有两条路:
8
- * 1. **内置**:`scoped-memory` 是平台自带的最小实现,作为默认值存在——没有它,
9
- * 一个没声明 provider 的产品就会没有记忆,那是最糟的默认。
10
- * 2. **外部**:产品在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是
11
- * 产品目录内的相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions`
12
- * 同一信任模型:仓库内代码、过准入扫描、进程内运行。
7
+ * 默认实现是 `hermes-scoped`(`@njuptlzf/pi-hermes-memory`),与其他提供方走**同一条**
8
+ * 动态加载路径——静态 import 会把外部包的源码/类型拉进本仓的 tsc program与 tsx 入口,
9
+ * 跨仓源码进他人编译单元是最难收拾的一类耦合。默认模块说明符内建在下面,
10
+ * 由 `ensureDefaultMemoryProvider()` 在会话创建前惰性加载并注册。
11
+ *
12
+ * 产品也可以在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是产品目录内的
13
+ * 相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions` 同一信任模型:
14
+ * 仓库内代码、过准入扫描、进程内运行。
13
15
  *
14
16
  * 两条刻意选择:
15
17
  * - **不可用即报错,不静默降级**。选了没装的 provider 就抛,并列出已注册 id。
16
18
  * 静默回落默认实现,会让"我换了引擎"和"我忘了装"看起来一模一样。
17
- * - **模块用动态 import**。静态导入会把提供方(可能是第三方包)的整棵源码拉进
18
- * 本仓的 tsc program,跨仓源码进他人编译单元是最难收拾的一类耦合。
19
+ * - **模块用动态 import**(理由见上)。
19
20
  */
20
21
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
21
22
  import type { MemoryProvider } from "@njuptlzf/agent-chat-protocol";
22
23
  /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
23
- export declare const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
24
+ export declare const DEFAULT_MEMORY_PROVIDER_ID = "hermes-scoped";
25
+ /**
26
+ * 默认实现的模块说明符。作为 server 的直接依赖随包安装;用裸说明符走动态 import,
27
+ * 由 Node 按 exports 条件解析(编译产物走 dist,内部 source 条件走 src)。
28
+ */
29
+ export declare const DEFAULT_MEMORY_PROVIDER_MODULE = "@njuptlzf/pi-hermes-memory/scoped-provider";
30
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
31
+ export declare function providerSupportsSharedProfile(provider: MemoryProvider<ExtensionAPI>): boolean;
24
32
  /**
25
33
  * 注册一个提供方。
26
34
  *
@@ -40,6 +48,7 @@ export declare function resolveProviderModuleEntry(entry: string, productDir: st
40
48
  * 读 env / 拉子进程在这里同样是跨层能力。
41
49
  */
42
50
  export declare function loadMemoryProviderModule(entry: string, productDir: string): Promise<MemoryProvider<ExtensionAPI>>;
51
+ export declare function ensureDefaultMemoryProvider(): Promise<MemoryProvider<ExtensionAPI>>;
43
52
  export declare function listMemoryProviders(): Array<{
44
53
  id: string;
45
54
  version: string;
@@ -4,18 +4,19 @@
4
4
  * 服务器只认 id,不认实现:换记忆引擎 = 换 manifest 里的 `agent.memory.provider`,
5
5
  * 本文件之外的服务器代码一行不动。
6
6
  *
7
- * 注册有两条路:
8
- * 1. **内置**:`scoped-memory` 是平台自带的最小实现,作为默认值存在——没有它,
9
- * 一个没声明 provider 的产品就会没有记忆,那是最糟的默认。
10
- * 2. **外部**:产品在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是
11
- * 产品目录内的相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions`
12
- * 同一信任模型:仓库内代码、过准入扫描、进程内运行。
7
+ * 默认实现是 `hermes-scoped`(`@njuptlzf/pi-hermes-memory`),与其他提供方走**同一条**
8
+ * 动态加载路径——静态 import 会把外部包的源码/类型拉进本仓的 tsc program与 tsx 入口,
9
+ * 跨仓源码进他人编译单元是最难收拾的一类耦合。默认模块说明符内建在下面,
10
+ * 由 `ensureDefaultMemoryProvider()` 在会话创建前惰性加载并注册。
11
+ *
12
+ * 产品也可以在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是产品目录内的
13
+ * 相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions` 同一信任模型:
14
+ * 仓库内代码、过准入扫描、进程内运行。
13
15
  *
14
16
  * 两条刻意选择:
15
17
  * - **不可用即报错,不静默降级**。选了没装的 provider 就抛,并列出已注册 id。
16
18
  * 静默回落默认实现,会让"我换了引擎"和"我忘了装"看起来一模一样。
17
- * - **模块用动态 import**。静态导入会把提供方(可能是第三方包)的整棵源码拉进
18
- * 本仓的 tsc program,跨仓源码进他人编译单元是最难收拾的一类耦合。
19
+ * - **模块用动态 import**(理由见上)。
19
20
  */
20
21
  var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
21
22
  if (typeof path === "string" && /^\.\.?\//.test(path)) {
@@ -29,47 +30,17 @@ import { existsSync, readFileSync } from "node:fs";
29
30
  import { createRequire } from "node:module";
30
31
  import * as path from "node:path";
31
32
  import { pathToFileURL } from "node:url";
32
- import { scopedMemory } from "pi-scoped-memory";
33
33
  import { auditExtensionSource } from "./extension-admission.js";
34
34
  /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
35
- export const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
35
+ export const DEFAULT_MEMORY_PROVIDER_ID = "hermes-scoped";
36
+ /**
37
+ * 默认实现的模块说明符。作为 server 的直接依赖随包安装;用裸说明符走动态 import,
38
+ * 由 Node 按 exports 条件解析(编译产物走 dist,内部 source 条件走 src)。
39
+ */
40
+ export const DEFAULT_MEMORY_PROVIDER_MODULE = "@njuptlzf/pi-hermes-memory/scoped-provider";
36
41
  const requireFromRoot = createRequire(import.meta.url);
37
- function installedVersion(pkg) {
38
- try {
39
- const parsed = requireFromRoot(`${pkg}/package.json`);
40
- return typeof parsed.version === "string" ? parsed.version : "unknown";
41
- }
42
- catch {
43
- // Version is for logs, not behaviour: a missing package.json must not break open().
44
- return "unknown";
45
- }
46
- }
47
- const scopedMemoryProvider = {
48
- id: DEFAULT_MEMORY_PROVIDER_ID,
49
- version: installedVersion("pi-scoped-memory"),
50
- async open(ctx) {
51
- const dir = ctx.storageRoot;
52
- const { rm } = await import("node:fs/promises");
53
- return {
54
- providerId: DEFAULT_MEMORY_PROVIDER_ID,
55
- // scopedMemory appends its own snapshot in before_agent_start.
56
- selfInjects: true,
57
- factory: scopedMemory({ dir, autoCapture: true }),
58
- async promptSection() {
59
- return "";
60
- },
61
- async erase() {
62
- // Its own file is <dir>/entries.jsonl; the directory is host-allocated,
63
- // so removing it is exactly one tenant's worth of data.
64
- await rm(dir, { recursive: true, force: true });
65
- },
66
- async dispose() { },
67
- };
68
- },
69
- };
70
- const registry = new Map([
71
- [scopedMemoryProvider.id, scopedMemoryProvider],
72
- ]);
42
+ /** 注册表。默认实现首次会话时惰性注册,其余由 manifest 声明的模块加载进来。 */
43
+ const registry = new Map();
73
44
  /** 已加载的外部模块,按解析后的绝对路径去重:同一文件 import 两次不该注册两次。 */
74
45
  const loadedModules = new Map();
75
46
  function assertProviderShape(candidate, source) {
@@ -86,8 +57,23 @@ function assertProviderShape(candidate, source) {
86
57
  if (typeof provider.open !== "function") {
87
58
  throw new Error(`${source}: provider.open must be a function`);
88
59
  }
60
+ // capabilities 可选,但一旦出现就必须是合法形状——一个拼错的能力声明等于没有声明,
61
+ // 而宿主会据此决定是否告警,静默吞掉会让告警永远不触发。
62
+ if (provider.capabilities !== undefined) {
63
+ if (typeof provider.capabilities !== "object" || provider.capabilities === null) {
64
+ throw new Error(`${source}: provider.capabilities must be an object`);
65
+ }
66
+ const shared = provider.capabilities.sharedProfile;
67
+ if (shared !== undefined && typeof shared !== "boolean") {
68
+ throw new Error(`${source}: provider.capabilities.sharedProfile must be a boolean`);
69
+ }
70
+ }
89
71
  return provider;
90
72
  }
73
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
74
+ export function providerSupportsSharedProfile(provider) {
75
+ return provider.capabilities?.sharedProfile === true;
76
+ }
91
77
  /**
92
78
  * 注册一个提供方。
93
79
  *
@@ -159,6 +145,43 @@ export async function loadMemoryProviderModule(entry, productDir) {
159
145
  throw error;
160
146
  }
161
147
  }
148
+ /**
149
+ * 惰性加载并注册默认实现。
150
+ *
151
+ * 默认 provider 与其他实现走同一条动态 import 路径,外部包的源码/类型不进本仓 tsc program。
152
+ * 但**不能**用裸说明符 import:在 `node --import tsx` 的入口下,包的 `types` 条件会被优先
153
+ * 解析成 `dist/scoped/provider.d.ts` 当代码执行,报 `ReferenceError: provider is not defined`
154
+ * (live:fixture 实测)。所以这里解析包根后按**确定的 dist 文件路径** import,绕开所有条件。
155
+ * 第一次创建会话时加载、过形状校验、注册;缓存一次,多次调用复用。
156
+ */
157
+ let defaultProviderLoad;
158
+ export async function ensureDefaultMemoryProvider() {
159
+ // A product may have declared the same provider explicitly via its own adapter
160
+ // module. In that case the id is already registered — reuse it instead of
161
+ // importing a second module instance and colliding on the id.
162
+ const existing = registry.get(DEFAULT_MEMORY_PROVIDER_ID);
163
+ if (existing)
164
+ return existing;
165
+ if (defaultProviderLoad)
166
+ return defaultProviderLoad;
167
+ defaultProviderLoad = (async () => {
168
+ const pkgJson = requireFromRoot.resolve("@njuptlzf/pi-hermes-memory/package.json");
169
+ const entry = path.join(path.dirname(pkgJson), "dist", "scoped", "provider.js");
170
+ const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(entry).href)));
171
+ const provider = assertProviderShape(mod.default, `default memory provider "${DEFAULT_MEMORY_PROVIDER_MODULE}"`);
172
+ registerMemoryProvider(provider);
173
+ return provider;
174
+ })();
175
+ try {
176
+ return await defaultProviderLoad;
177
+ }
178
+ catch (error) {
179
+ // A failed default load must not poison the cache: fixing the install and
180
+ // retrying is the normal recovery path.
181
+ defaultProviderLoad = undefined;
182
+ throw error;
183
+ }
184
+ }
162
185
  export function listMemoryProviders() {
163
186
  return [...registry.values()].map((provider) => ({
164
187
  id: provider.id,
package/dist/server.js CHANGED
@@ -1793,6 +1793,11 @@ export function createChatServer(deps) {
1793
1793
  dataDir: deps.dataDir,
1794
1794
  tier,
1795
1795
  qual: scope,
1796
+ // Each member is an independent concurrent worker; give its memory a
1797
+ // distinct root so two live hermes handles never claim the same scope
1798
+ // (the provider enforces one handle per root). Prompt/history/tools
1799
+ // stay scoped by `qual` above.
1800
+ memoryScopeKey: `${scope}__${ctx.jobId.replace(/[^A-Za-z0-9_-]/g, "_")}`,
1796
1801
  persona: job.persona,
1797
1802
  history,
1798
1803
  mcpConfig: deps.mcpConfig,
package/dist/session.d.ts CHANGED
@@ -94,6 +94,12 @@ export interface CreateProductSessionOptions {
94
94
  * syllabus. Omit or "" for products without qualifications.
95
95
  */
96
96
  qual?: string;
97
+ /**
98
+ * 仅用于记忆 storageRoot 的作用域键。默认等于 `qual`;编排层的并发成员会话传入各自的
99
+ * job/phase 键,避免多个 hermes handle 同时开在同一个根上(provider 按根独占句柄)。
100
+ * 不影响提示词、历史或工具的作用域——那些仍由 `qual` 决定。
101
+ */
102
+ memoryScopeKey?: string;
97
103
  /**
98
104
  * Which assistant persona this session is (). Omit for the product
99
105
  * product default. It only swaps prompt/skills here; the tool whitelist is
@@ -197,6 +203,11 @@ export declare function compileSystemPrompt(product: LoadedProduct, qual: string
197
203
  allowTools?: string[];
198
204
  disabledTools: string[];
199
205
  };
206
+ /**
207
+ * 产品依赖跨会话画像,但选中的 provider 没声明该能力时给宿主的可读告警(C6)。
208
+ * 导出为纯函数,便于契约测试钉住文案;返回 null 表示无需告警。
209
+ */
210
+ export declare function sharedProfileMismatchWarning(requiresSharedProfile: boolean, providerSupports: boolean): string | null;
200
211
  /**
201
212
  * Build a pi session locked down for multi-user serving:
202
213
  * - no built-in tools (no bash / read / write / edit), verified by test
package/dist/session.js CHANGED
@@ -1,10 +1,10 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { readFileSync } from "node:fs";
2
+ import { mkdirSync, readFileSync } from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { Type } from "typebox";
5
5
  import { createAgentSession, createMcpExtension, DefaultResourceLoader, defineTool, initTheme, loadSkillsFromDir, stripFrontmatter, ModelRuntime, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
6
6
  import { toProxySpawn } from "./mcp-config.js";
7
- import { loadMemoryProviderModule, resolveMemoryProvider } from "./memory-providers.js";
7
+ import { ensureDefaultMemoryProvider, loadMemoryProviderModule, providerSupportsSharedProfile, resolveMemoryProvider } from "./memory-providers.js";
8
8
  import { agentFor, resolveTier } from "./manifest.js";
9
9
  import { applyPersonaOverride } from "./persona-config.js";
10
10
  import { validateModelsCost } from "./cost-model.js";
@@ -358,6 +358,17 @@ export function compileSystemPrompt(product, qual, persona, override) {
358
358
  * session also means a crashed session cannot leak a handle into the next one.
359
359
  */
360
360
  const memorySessionsByAgent = new WeakMap();
361
+ /**
362
+ * 产品依赖跨会话画像,但选中的 provider 没声明该能力时给宿主的可读告警(C6)。
363
+ * 导出为纯函数,便于契约测试钉住文案;返回 null 表示无需告警。
364
+ */
365
+ export function sharedProfileMismatchWarning(requiresSharedProfile, providerSupports) {
366
+ if (!requiresSharedProfile || providerSupports)
367
+ return null;
368
+ return "此产品声明依赖跨会话用户画像(agent.memory.requiresSharedProfile),"
369
+ + "但所选记忆 provider 未声明支持该能力(capabilities.sharedProfile);"
370
+ + "用户偏好不会在 scope 之间共享。请改用支持该能力的 provider,或移除该依赖声明。";
371
+ }
361
372
  /**
362
373
  * Build a pi session locked down for multi-user serving:
363
374
  * - no built-in tools (no bash / read / write / edit), verified by test
@@ -469,17 +480,42 @@ export async function createProductSession(opts) {
469
480
  // `hermes-scoped` exists until the product declares the module that provides
470
481
  // it. Loading is per-file memoised, so this is one dynamic import per process.
471
482
  if (product.memoryEnabled) {
483
+ // Product-declared modules first: if one of them already provides the default
484
+ // id, ensureDefaultMemoryProvider() reuses it instead of importing a second
485
+ // instance. The default itself is a lazy dynamic import so the external
486
+ // package's source/types stay out of our tsc program and tsx entrypoints.
472
487
  for (const entry of product.memoryProviderModules) {
473
488
  await loadMemoryProviderModule(entry, product.dir);
474
489
  }
490
+ await ensureDefaultMemoryProvider();
475
491
  }
476
492
  // Two disjoint roots per session: the scope (user × product × qual) and the
477
493
  // user's cross-scope profile. Siblings, not nested — erasing one qualification
478
494
  // must not delete the user's identity, and the provider enforces that too.
479
- const memorySession = product.memoryEnabled
480
- ? await resolveMemoryProvider(product.memoryProviderId).open({
481
- storageRoot: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"),
482
- sharedRoot: path.join(opts.dataDir, "memory", opts.userId, "profile"),
495
+ const memoryProvider = product.memoryEnabled
496
+ ? resolveMemoryProvider(product.memoryProviderId)
497
+ : null;
498
+ // C6: a product may declare it depends on cross-scope profile. If the chosen
499
+ // provider does not advertise that capability, warn instead of letting the
500
+ // capability silently disappear. Warning only — the session still opens.
501
+ if (memoryProvider) {
502
+ const warning = sharedProfileMismatchWarning(product.requiresSharedProfile, providerSupportsSharedProfile(memoryProvider));
503
+ if (warning)
504
+ opts.onUINotify?.(warning, "warning");
505
+ }
506
+ // The host owns the roots, so it must materialise them before open(). The
507
+ // old built-in created parents lazily on write; hermes uses mkdtemp under
508
+ // storageRoot and expects the host-allocated directory to already exist.
509
+ const storageRoot = path.join(opts.dataDir, "memory", opts.userId, opts.memoryScopeKey || opts.qual || "default");
510
+ const sharedRoot = path.join(opts.dataDir, "memory", opts.userId, "profile");
511
+ if (memoryProvider) {
512
+ mkdirSync(storageRoot, { recursive: true });
513
+ mkdirSync(sharedRoot, { recursive: true });
514
+ }
515
+ const memorySession = memoryProvider
516
+ ? await memoryProvider.open({
517
+ storageRoot,
518
+ sharedRoot,
483
519
  agentDir: opts.dataDir,
484
520
  scope: { userId: opts.userId, productId: product.manifest.id, qual: opts.qual || "" },
485
521
  })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@njuptlzf/agent-chat-server",
3
- "version": "0.5.1",
3
+ "version": "0.7.0",
4
4
  "description": "agentChat platform kernel: sessions, authz, billing, audit, model/MCP/persona config planes, and the product-directory loader.",
5
5
  "type": "module",
6
6
  "license": "Apache-2.0",
@@ -55,10 +55,9 @@
55
55
  },
56
56
  "dependencies": {
57
57
  "@earendil-works/pi-coding-agent": "1.5.2",
58
- "@njuptlzf/agent-chat-protocol": "^0.5.0",
59
- "@njuptlzf/pi-hermes-memory": "0.11.0-scoped.1",
58
+ "@njuptlzf/agent-chat-protocol": "^0.7.0",
59
+ "@njuptlzf/pi-hermes-memory": "0.11.0-scoped.5",
60
60
  "casbin": "^5.51.1",
61
- "pi-scoped-memory": "^0.3.0",
62
61
  "taskflow-core": "1.0.0",
63
62
  "typebox": "^1.3.27",
64
63
  "yaml": "^2.8.0"
@@ -20,7 +20,7 @@ import { createRequire } from "node:module";
20
20
  import { spawnSync } from "node:child_process";
21
21
  import process from "node:process";
22
22
 
23
- const CLI_VERSION = "0.5.1";
23
+ const CLI_VERSION = "0.7.0";
24
24
  const MIN_SERVER = "0.2.0";
25
25
  const PKG = {
26
26
  protocol: "@njuptlzf/agent-chat-protocol",
@@ -215,9 +215,9 @@ function packageTemplate(o) {
215
215
  private: true,
216
216
  type: "module",
217
217
  dependencies: {
218
- [PKG.protocol]: "^0.5.0",
219
- [PKG.server]: "^0.5.0",
220
- [PKG.web]: "^0.5.0",
218
+ [PKG.protocol]: "^0.7.0",
219
+ [PKG.server]: "^0.7.0",
220
+ [PKG.web]: "^0.7.0",
221
221
  },
222
222
  devDependencies: {
223
223
  tsx: "^4.20.0",
@@ -408,7 +408,7 @@ function checkDeps(add, dir) {
408
408
  const all = { ...(pj.dependencies ?? {}), ...(pj.devDependencies ?? {}) };
409
409
  const missing = Object.values(PKG).filter((n) => !(n in all));
410
410
  if (missing.length) add("FAIL", "deps", `未声明平台依赖:${missing.join("、")}`,
411
- `npm i ${PKG.protocol}@^0.5.0 ${PKG.server}@^0.5.0 ${PKG.web}@^0.5.0`);
411
+ `npm i ${PKG.protocol}@^0.7.0 ${PKG.server}@^0.7.0 ${PKG.web}@^0.7.0`);
412
412
  else add("OK", "deps", "三个平台包依赖已声明");
413
413
 
414
414
  try {
package/src/manifest.ts CHANGED
@@ -24,6 +24,11 @@ export interface LoadedProduct {
24
24
  memoryEnabled: boolean;
25
25
  /** Provider id from `agent.memory.provider`; falls back to the platform default. */
26
26
  memoryProviderId: string;
27
+ /**
28
+ * 产品是否声明依赖跨会话用户画像(`agent.memory.requiresSharedProfile`)。
29
+ * 宿主据此在选中的 provider 不支持该能力时告警(C6)。缺省 false。
30
+ */
31
+ requiresSharedProfile: boolean;
27
32
  /**
28
33
  * 外部提供方模块(`agent.memoryProviders`),原样保留声明顺序。
29
34
  * 加载在会话创建前完成——解析与准入扫描要读文件,manifest 解析是同步的。
@@ -559,6 +564,9 @@ export function loadProduct(dir: string): LoadedProduct {
559
564
  memoryProviderId: typeof manifest.agent.memory === "object" && manifest.agent.memory !== null
560
565
  ? manifest.agent.memory.provider ?? DEFAULT_MEMORY_PROVIDER_ID
561
566
  : DEFAULT_MEMORY_PROVIDER_ID,
567
+ requiresSharedProfile: typeof manifest.agent.memory === "object" && manifest.agent.memory !== null
568
+ ? manifest.agent.memory.requiresSharedProfile === true
569
+ : false,
562
570
  memoryProviderModules: [...(manifest.agent.memoryProviders ?? [])],
563
571
  questionDirs,
564
572
  caseDirs,
@@ -4,18 +4,19 @@
4
4
  * 服务器只认 id,不认实现:换记忆引擎 = 换 manifest 里的 `agent.memory.provider`,
5
5
  * 本文件之外的服务器代码一行不动。
6
6
  *
7
- * 注册有两条路:
8
- * 1. **内置**:`scoped-memory` 是平台自带的最小实现,作为默认值存在——没有它,
9
- * 一个没声明 provider 的产品就会没有记忆,那是最糟的默认。
10
- * 2. **外部**:产品在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是
11
- * 产品目录内的相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions`
12
- * 同一信任模型:仓库内代码、过准入扫描、进程内运行。
7
+ * 默认实现是 `hermes-scoped`(`@njuptlzf/pi-hermes-memory`),与其他提供方走**同一条**
8
+ * 动态加载路径——静态 import 会把外部包的源码/类型拉进本仓的 tsc program与 tsx 入口,
9
+ * 跨仓源码进他人编译单元是最难收拾的一类耦合。默认模块说明符内建在下面,
10
+ * 由 `ensureDefaultMemoryProvider()` 在会话创建前惰性加载并注册。
11
+ *
12
+ * 产品也可以在 manifest 里声明 `agent.memoryProviders: [...]`,条目可以是产品目录内的
13
+ * 相对路径,也可以是包名(走 Node 解析)。外部模块与 `agent.extensions` 同一信任模型:
14
+ * 仓库内代码、过准入扫描、进程内运行。
13
15
  *
14
16
  * 两条刻意选择:
15
17
  * - **不可用即报错,不静默降级**。选了没装的 provider 就抛,并列出已注册 id。
16
18
  * 静默回落默认实现,会让"我换了引擎"和"我忘了装"看起来一模一样。
17
- * - **模块用动态 import**。静态导入会把提供方(可能是第三方包)的整棵源码拉进
18
- * 本仓的 tsc program,跨仓源码进他人编译单元是最难收拾的一类耦合。
19
+ * - **模块用动态 import**(理由见上)。
19
20
  */
20
21
 
21
22
  import { existsSync, readFileSync } from "node:fs";
@@ -23,52 +24,22 @@ import { createRequire } from "node:module";
23
24
  import * as path from "node:path";
24
25
  import { pathToFileURL } from "node:url";
25
26
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
26
- import { scopedMemory } from "pi-scoped-memory";
27
27
  import type { MemoryProvider, MemoryProviderModule } from "@njuptlzf/agent-chat-protocol";
28
28
  import { auditExtensionSource } from "./extension-admission.ts";
29
29
 
30
30
  /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
31
- export const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
31
+ export const DEFAULT_MEMORY_PROVIDER_ID = "hermes-scoped";
32
32
 
33
- const requireFromRoot = createRequire(import.meta.url);
33
+ /**
34
+ * 默认实现的模块说明符。作为 server 的直接依赖随包安装;用裸说明符走动态 import,
35
+ * 由 Node 按 exports 条件解析(编译产物走 dist,内部 source 条件走 src)。
36
+ */
37
+ export const DEFAULT_MEMORY_PROVIDER_MODULE = "@njuptlzf/pi-hermes-memory/scoped-provider";
34
38
 
35
- function installedVersion(pkg: string): string {
36
- try {
37
- const parsed = requireFromRoot(`${pkg}/package.json`) as { version?: unknown };
38
- return typeof parsed.version === "string" ? parsed.version : "unknown";
39
- } catch {
40
- // Version is for logs, not behaviour: a missing package.json must not break open().
41
- return "unknown";
42
- }
43
- }
39
+ const requireFromRoot = createRequire(import.meta.url);
44
40
 
45
- const scopedMemoryProvider: MemoryProvider<ExtensionAPI> = {
46
- id: DEFAULT_MEMORY_PROVIDER_ID,
47
- version: installedVersion("pi-scoped-memory"),
48
- async open(ctx) {
49
- const dir = ctx.storageRoot;
50
- const { rm } = await import("node:fs/promises");
51
- return {
52
- providerId: DEFAULT_MEMORY_PROVIDER_ID,
53
- // scopedMemory appends its own snapshot in before_agent_start.
54
- selfInjects: true,
55
- factory: scopedMemory({ dir, autoCapture: true }),
56
- async promptSection() {
57
- return "";
58
- },
59
- async erase() {
60
- // Its own file is <dir>/entries.jsonl; the directory is host-allocated,
61
- // so removing it is exactly one tenant's worth of data.
62
- await rm(dir, { recursive: true, force: true });
63
- },
64
- async dispose() {},
65
- };
66
- },
67
- };
68
-
69
- const registry = new Map<string, MemoryProvider<ExtensionAPI>>([
70
- [scopedMemoryProvider.id, scopedMemoryProvider],
71
- ]);
41
+ /** 注册表。默认实现首次会话时惰性注册,其余由 manifest 声明的模块加载进来。 */
42
+ const registry = new Map<string, MemoryProvider<ExtensionAPI>>();
72
43
 
73
44
  /** 已加载的外部模块,按解析后的绝对路径去重:同一文件 import 两次不该注册两次。 */
74
45
  const loadedModules = new Map<string, Promise<MemoryProvider<ExtensionAPI>>>();
@@ -87,9 +58,25 @@ function assertProviderShape(candidate: unknown, source: string): MemoryProvider
87
58
  if (typeof provider.open !== "function") {
88
59
  throw new Error(`${source}: provider.open must be a function`);
89
60
  }
61
+ // capabilities 可选,但一旦出现就必须是合法形状——一个拼错的能力声明等于没有声明,
62
+ // 而宿主会据此决定是否告警,静默吞掉会让告警永远不触发。
63
+ if (provider.capabilities !== undefined) {
64
+ if (typeof provider.capabilities !== "object" || provider.capabilities === null) {
65
+ throw new Error(`${source}: provider.capabilities must be an object`);
66
+ }
67
+ const shared = provider.capabilities.sharedProfile;
68
+ if (shared !== undefined && typeof shared !== "boolean") {
69
+ throw new Error(`${source}: provider.capabilities.sharedProfile must be a boolean`);
70
+ }
71
+ }
90
72
  return provider as MemoryProvider<ExtensionAPI>;
91
73
  }
92
74
 
75
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
76
+ export function providerSupportsSharedProfile(provider: MemoryProvider<ExtensionAPI>): boolean {
77
+ return provider.capabilities?.sharedProfile === true;
78
+ }
79
+
93
80
  /**
94
81
  * 注册一个提供方。
95
82
  *
@@ -167,6 +154,42 @@ export async function loadMemoryProviderModule(
167
154
  }
168
155
  }
169
156
 
157
+ /**
158
+ * 惰性加载并注册默认实现。
159
+ *
160
+ * 默认 provider 与其他实现走同一条动态 import 路径,外部包的源码/类型不进本仓 tsc program。
161
+ * 但**不能**用裸说明符 import:在 `node --import tsx` 的入口下,包的 `types` 条件会被优先
162
+ * 解析成 `dist/scoped/provider.d.ts` 当代码执行,报 `ReferenceError: provider is not defined`
163
+ * (live:fixture 实测)。所以这里解析包根后按**确定的 dist 文件路径** import,绕开所有条件。
164
+ * 第一次创建会话时加载、过形状校验、注册;缓存一次,多次调用复用。
165
+ */
166
+ let defaultProviderLoad: Promise<MemoryProvider<ExtensionAPI>> | undefined;
167
+
168
+ export async function ensureDefaultMemoryProvider(): Promise<MemoryProvider<ExtensionAPI>> {
169
+ // A product may have declared the same provider explicitly via its own adapter
170
+ // module. In that case the id is already registered — reuse it instead of
171
+ // importing a second module instance and colliding on the id.
172
+ const existing = registry.get(DEFAULT_MEMORY_PROVIDER_ID);
173
+ if (existing) return existing;
174
+ if (defaultProviderLoad) return defaultProviderLoad;
175
+ defaultProviderLoad = (async () => {
176
+ const pkgJson = requireFromRoot.resolve("@njuptlzf/pi-hermes-memory/package.json");
177
+ const entry = path.join(path.dirname(pkgJson), "dist", "scoped", "provider.js");
178
+ const mod = (await import(pathToFileURL(entry).href)) as MemoryProviderModule<ExtensionAPI>;
179
+ const provider = assertProviderShape(mod.default, `default memory provider "${DEFAULT_MEMORY_PROVIDER_MODULE}"`);
180
+ registerMemoryProvider(provider);
181
+ return provider;
182
+ })();
183
+ try {
184
+ return await defaultProviderLoad;
185
+ } catch (error) {
186
+ // A failed default load must not poison the cache: fixing the install and
187
+ // retrying is the normal recovery path.
188
+ defaultProviderLoad = undefined;
189
+ throw error;
190
+ }
191
+ }
192
+
170
193
  export function listMemoryProviders(): Array<{ id: string; version: string; default: boolean }> {
171
194
  return [...registry.values()].map((provider) => ({
172
195
  id: provider.id,
package/src/server.ts CHANGED
@@ -1992,6 +1992,11 @@ export function createChatServer(deps: ServerDeps): Server {
1992
1992
  dataDir: deps.dataDir,
1993
1993
  tier,
1994
1994
  qual: scope,
1995
+ // Each member is an independent concurrent worker; give its memory a
1996
+ // distinct root so two live hermes handles never claim the same scope
1997
+ // (the provider enforces one handle per root). Prompt/history/tools
1998
+ // stay scoped by `qual` above.
1999
+ memoryScopeKey: `${scope}__${ctx.jobId.replace(/[^A-Za-z0-9_-]/g, "_")}`,
1995
2000
  persona: job.persona,
1996
2001
  history,
1997
2002
  mcpConfig: deps.mcpConfig,
package/src/session.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
- import { readFileSync } from "node:fs";
2
+ import { mkdirSync, readFileSync } from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { Type } from "typebox";
5
5
  import {
@@ -25,7 +25,7 @@ import {
25
25
  } from "@earendil-works/pi-coding-agent";
26
26
  import type { McpServerDecl, MemoryProviderSession } from "@njuptlzf/agent-chat-protocol";
27
27
  import { toProxySpawn, type McpConfigStore } from "./mcp-config.ts";
28
- import { loadMemoryProviderModule, resolveMemoryProvider } from "./memory-providers.ts";
28
+ import { ensureDefaultMemoryProvider, loadMemoryProviderModule, providerSupportsSharedProfile, resolveMemoryProvider } from "./memory-providers.ts";
29
29
  import type { LoadedProduct, ResolvedTier, ToolContext } from "./manifest.ts";
30
30
  import { agentFor, resolveTier } from "./manifest.ts";
31
31
  import { applyPersonaOverride, type PersonaConfigStore, type PersonaOverride } from "./persona-config.ts";
@@ -191,6 +191,12 @@ export interface CreateProductSessionOptions {
191
191
  * syllabus. Omit or "" for products without qualifications.
192
192
  */
193
193
  qual?: string;
194
+ /**
195
+ * 仅用于记忆 storageRoot 的作用域键。默认等于 `qual`;编排层的并发成员会话传入各自的
196
+ * job/phase 键,避免多个 hermes handle 同时开在同一个根上(provider 按根独占句柄)。
197
+ * 不影响提示词、历史或工具的作用域——那些仍由 `qual` 决定。
198
+ */
199
+ memoryScopeKey?: string;
194
200
  /**
195
201
  * Which assistant persona this session is (). Omit for the product
196
202
  * product default. It only swaps prompt/skills here; the tool whitelist is
@@ -491,6 +497,20 @@ export function compileSystemPrompt(
491
497
  */
492
498
  const memorySessionsByAgent = new WeakMap<AgentSession, MemoryProviderSession<ExtensionAPI>>();
493
499
 
500
+ /**
501
+ * 产品依赖跨会话画像,但选中的 provider 没声明该能力时给宿主的可读告警(C6)。
502
+ * 导出为纯函数,便于契约测试钉住文案;返回 null 表示无需告警。
503
+ */
504
+ export function sharedProfileMismatchWarning(
505
+ requiresSharedProfile: boolean,
506
+ providerSupports: boolean,
507
+ ): string | null {
508
+ if (!requiresSharedProfile || providerSupports) return null;
509
+ return "此产品声明依赖跨会话用户画像(agent.memory.requiresSharedProfile),"
510
+ + "但所选记忆 provider 未声明支持该能力(capabilities.sharedProfile);"
511
+ + "用户偏好不会在 scope 之间共享。请改用支持该能力的 provider,或移除该依赖声明。";
512
+ }
513
+
494
514
  /**
495
515
  * Build a pi session locked down for multi-user serving:
496
516
  * - no built-in tools (no bash / read / write / edit), verified by test
@@ -608,17 +628,44 @@ export async function createProductSession(opts: CreateProductSessionOptions): P
608
628
  // `hermes-scoped` exists until the product declares the module that provides
609
629
  // it. Loading is per-file memoised, so this is one dynamic import per process.
610
630
  if (product.memoryEnabled) {
631
+ // Product-declared modules first: if one of them already provides the default
632
+ // id, ensureDefaultMemoryProvider() reuses it instead of importing a second
633
+ // instance. The default itself is a lazy dynamic import so the external
634
+ // package's source/types stay out of our tsc program and tsx entrypoints.
611
635
  for (const entry of product.memoryProviderModules) {
612
636
  await loadMemoryProviderModule(entry, product.dir);
613
637
  }
638
+ await ensureDefaultMemoryProvider();
614
639
  }
615
640
  // Two disjoint roots per session: the scope (user × product × qual) and the
616
641
  // user's cross-scope profile. Siblings, not nested — erasing one qualification
617
642
  // must not delete the user's identity, and the provider enforces that too.
618
- const memorySession = product.memoryEnabled
619
- ? await resolveMemoryProvider(product.memoryProviderId).open({
620
- storageRoot: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"),
621
- sharedRoot: path.join(opts.dataDir, "memory", opts.userId, "profile"),
643
+ const memoryProvider = product.memoryEnabled
644
+ ? resolveMemoryProvider(product.memoryProviderId)
645
+ : null;
646
+ // C6: a product may declare it depends on cross-scope profile. If the chosen
647
+ // provider does not advertise that capability, warn instead of letting the
648
+ // capability silently disappear. Warning only — the session still opens.
649
+ if (memoryProvider) {
650
+ const warning = sharedProfileMismatchWarning(
651
+ product.requiresSharedProfile,
652
+ providerSupportsSharedProfile(memoryProvider),
653
+ );
654
+ if (warning) opts.onUINotify?.(warning, "warning");
655
+ }
656
+ // The host owns the roots, so it must materialise them before open(). The
657
+ // old built-in created parents lazily on write; hermes uses mkdtemp under
658
+ // storageRoot and expects the host-allocated directory to already exist.
659
+ const storageRoot = path.join(opts.dataDir, "memory", opts.userId, opts.memoryScopeKey || opts.qual || "default");
660
+ const sharedRoot = path.join(opts.dataDir, "memory", opts.userId, "profile");
661
+ if (memoryProvider) {
662
+ mkdirSync(storageRoot, { recursive: true });
663
+ mkdirSync(sharedRoot, { recursive: true });
664
+ }
665
+ const memorySession = memoryProvider
666
+ ? await memoryProvider.open({
667
+ storageRoot,
668
+ sharedRoot,
622
669
  agentDir: opts.dataDir,
623
670
  scope: { userId: opts.userId, productId: product.manifest.id, qual: opts.qual || "" },
624
671
  })