@njuptlzf/agent-chat-server 0.5.0 → 0.6.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,
@@ -21,6 +21,8 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
21
21
  import type { MemoryProvider } from "@njuptlzf/agent-chat-protocol";
22
22
  /** 不指定时的实现。与 protocol 的 `agent.memory === true` 对齐。 */
23
23
  export declare const DEFAULT_MEMORY_PROVIDER_ID = "scoped-memory";
24
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
25
+ export declare function providerSupportsSharedProfile(provider: MemoryProvider<ExtensionAPI>): boolean;
24
26
  /**
25
27
  * 注册一个提供方。
26
28
  *
@@ -47,6 +47,9 @@ function installedVersion(pkg) {
47
47
  const scopedMemoryProvider = {
48
48
  id: DEFAULT_MEMORY_PROVIDER_ID,
49
49
  version: installedVersion("pi-scoped-memory"),
50
+ // 历史实现只读 storageRoot、不读 sharedRoot,没有任何跨 scope 画像能力。
51
+ // 显式声明 false,让宿主能在产品依赖该能力时告警(C6)。
52
+ capabilities: { sharedProfile: false },
50
53
  async open(ctx) {
51
54
  const dir = ctx.storageRoot;
52
55
  const { rm } = await import("node:fs/promises");
@@ -86,8 +89,23 @@ function assertProviderShape(candidate, source) {
86
89
  if (typeof provider.open !== "function") {
87
90
  throw new Error(`${source}: provider.open must be a function`);
88
91
  }
92
+ // capabilities 可选,但一旦出现就必须是合法形状——一个拼错的能力声明等于没有声明,
93
+ // 而宿主会据此决定是否告警,静默吞掉会让告警永远不触发。
94
+ if (provider.capabilities !== undefined) {
95
+ if (typeof provider.capabilities !== "object" || provider.capabilities === null) {
96
+ throw new Error(`${source}: provider.capabilities must be an object`);
97
+ }
98
+ const shared = provider.capabilities.sharedProfile;
99
+ if (shared !== undefined && typeof shared !== "boolean") {
100
+ throw new Error(`${source}: provider.capabilities.sharedProfile must be a boolean`);
101
+ }
102
+ }
89
103
  return provider;
90
104
  }
105
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
106
+ export function providerSupportsSharedProfile(provider) {
107
+ return provider.capabilities?.sharedProfile === true;
108
+ }
91
109
  /**
92
110
  * 注册一个提供方。
93
111
  *
package/dist/session.d.ts CHANGED
@@ -197,6 +197,11 @@ export declare function compileSystemPrompt(product: LoadedProduct, qual: string
197
197
  allowTools?: string[];
198
198
  disabledTools: string[];
199
199
  };
200
+ /**
201
+ * 产品依赖跨会话画像,但选中的 provider 没声明该能力时给宿主的可读告警(C6)。
202
+ * 导出为纯函数,便于契约测试钉住文案;返回 null 表示无需告警。
203
+ */
204
+ export declare function sharedProfileMismatchWarning(requiresSharedProfile: boolean, providerSupports: boolean): string | null;
200
205
  /**
201
206
  * Build a pi session locked down for multi-user serving:
202
207
  * - no built-in tools (no bash / read / write / edit), verified by test
package/dist/session.js CHANGED
@@ -4,7 +4,7 @@ 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 { 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
@@ -476,8 +487,19 @@ export async function createProductSession(opts) {
476
487
  // Two disjoint roots per session: the scope (user × product × qual) and the
477
488
  // user's cross-scope profile. Siblings, not nested — erasing one qualification
478
489
  // must not delete the user's identity, and the provider enforces that too.
479
- const memorySession = product.memoryEnabled
480
- ? await resolveMemoryProvider(product.memoryProviderId).open({
490
+ const memoryProvider = product.memoryEnabled
491
+ ? resolveMemoryProvider(product.memoryProviderId)
492
+ : null;
493
+ // C6: a product may declare it depends on cross-scope profile. If the chosen
494
+ // provider does not advertise that capability, warn instead of letting the
495
+ // capability silently disappear. Warning only — the session still opens.
496
+ if (memoryProvider) {
497
+ const warning = sharedProfileMismatchWarning(product.requiresSharedProfile, providerSupportsSharedProfile(memoryProvider));
498
+ if (warning)
499
+ opts.onUINotify?.(warning, "warning");
500
+ }
501
+ const memorySession = memoryProvider
502
+ ? await memoryProvider.open({
481
503
  storageRoot: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"),
482
504
  sharedRoot: path.join(opts.dataDir, "memory", opts.userId, "profile"),
483
505
  agentDir: opts.dataDir,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@njuptlzf/agent-chat-server",
3
- "version": "0.5.0",
3
+ "version": "0.6.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,8 +55,8 @@
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.6.0",
59
+ "@njuptlzf/pi-hermes-memory": "0.11.0-scoped.5",
60
60
  "casbin": "^5.51.1",
61
61
  "pi-scoped-memory": "^0.3.0",
62
62
  "taskflow-core": "1.0.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.0";
23
+ const CLI_VERSION = "0.6.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.6.0",
219
+ [PKG.server]: "^0.6.0",
220
+ [PKG.web]: "^0.6.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.6.0 ${PKG.server}@^0.6.0 ${PKG.web}@^0.6.0`);
412
412
  else add("OK", "deps", "三个平台包依赖已声明");
413
413
 
414
414
  try {
@@ -712,6 +712,45 @@ function checkTestScripts(add, dir, opts) {
712
712
  return runs;
713
713
  }
714
714
 
715
+ /**
716
+ * 工具 schema 的 TypeBox 越界构造子(启发式,只给 WARN)。
717
+ *
718
+ * pi 按 JSON Schema 校验工具参数(`@earendil-works/pi-schema`):`Refine` 静默不跑、
719
+ * `BigInt`/`Undefined`/`Void` 拒绝**每一个**参数(工具永远调不通)、`Codec` 不解码、
720
+ * `Format.Set` 不检查。四者都不报编译错,只在运行期让约束或工具本身失效——没有别的
721
+ * 门禁能抓到,所以在这里给一条建议。只 WARN:同一构造子也可能用在非工具 schema 上。
722
+ */
723
+ const TOOL_SCHEMA_TRAPS = [
724
+ [/Type\.Refine\s*\(/, "Type.Refine() 不跑,约束需挪进 execute() 自己校验"],
725
+ [/Type\.(?:BigInt|Undefined|Void)\s*\(/, "BigInt()/Undefined()/Void() 会拒绝每一个参数(工具永远调不通)"],
726
+ [/Type\.Codec\s*\(/, "Type.Codec() 不解码,execute() 收到的是 JSON 值"],
727
+ [/Format\.Set\s*\(/, "Format.Set() 注册的格式不检查"],
728
+ ];
729
+
730
+ function checkToolSchemas(add, dir) {
731
+ const hits = [];
732
+ for (const f of walkFiles(dir).filter((f) => /\.(ts|tsx)$/.test(f))) {
733
+ if (/[\\/](test|tests|e2e)[\\/]/.test(f)) continue; // 测试里造反例不算产品用法
734
+ const text = stripComments(readText(path.dirname(f), path.basename(f)));
735
+ if (!text) continue;
736
+ const rel = path.relative(dir, f).replace(/\\/g, "/");
737
+ for (const [re, why] of TOOL_SCHEMA_TRAPS) {
738
+ if (re.test(text)) hits.push(`${rel}:${why}`);
739
+ }
740
+ }
741
+ if (hits.length === 0) {
742
+ add("OK", "tool-schema", "未检出 pi 不支持的 TypeBox 构造子");
743
+ return;
744
+ }
745
+ add(
746
+ "WARN",
747
+ "tool-schema",
748
+ `检出 ${hits.length} 处 pi 工具参数校验不生效的 TypeBox 构造子`,
749
+ `${hits.join(";")}。工具 schema 改用 JSON Schema 子集(Object/String/Number/Boolean/Array/Optional/Union/Literal),` +
750
+ "表达不了的约束挪进 execute() 自己校验;若不是工具 schema 可忽略本条",
751
+ );
752
+ }
753
+
715
754
  function checkTooling(add, dir) {
716
755
  const wf = path.join(dir, ".github", "workflows");
717
756
  const wfFiles = fs.existsSync(wf) ? fs.readdirSync(wf).filter((f) => /\.ya?ml$/.test(f)) : [];
@@ -765,6 +804,7 @@ function check(opts, dir) {
765
804
  const caps = checkCapabilities(add, dir);
766
805
  const runs = checkTestScripts(add, dir, opts);
767
806
  checkTooling(add, dir);
807
+ checkToolSchemas(add, dir);
768
808
  if (opts.deep) checkDeep(add, dir);
769
809
 
770
810
  const failures = results.filter((r) => r.level === "FAIL");
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,
@@ -45,6 +45,9 @@ function installedVersion(pkg: string): string {
45
45
  const scopedMemoryProvider: MemoryProvider<ExtensionAPI> = {
46
46
  id: DEFAULT_MEMORY_PROVIDER_ID,
47
47
  version: installedVersion("pi-scoped-memory"),
48
+ // 历史实现只读 storageRoot、不读 sharedRoot,没有任何跨 scope 画像能力。
49
+ // 显式声明 false,让宿主能在产品依赖该能力时告警(C6)。
50
+ capabilities: { sharedProfile: false },
48
51
  async open(ctx) {
49
52
  const dir = ctx.storageRoot;
50
53
  const { rm } = await import("node:fs/promises");
@@ -87,9 +90,25 @@ function assertProviderShape(candidate: unknown, source: string): MemoryProvider
87
90
  if (typeof provider.open !== "function") {
88
91
  throw new Error(`${source}: provider.open must be a function`);
89
92
  }
93
+ // capabilities 可选,但一旦出现就必须是合法形状——一个拼错的能力声明等于没有声明,
94
+ // 而宿主会据此决定是否告警,静默吞掉会让告警永远不触发。
95
+ if (provider.capabilities !== undefined) {
96
+ if (typeof provider.capabilities !== "object" || provider.capabilities === null) {
97
+ throw new Error(`${source}: provider.capabilities must be an object`);
98
+ }
99
+ const shared = provider.capabilities.sharedProfile;
100
+ if (shared !== undefined && typeof shared !== "boolean") {
101
+ throw new Error(`${source}: provider.capabilities.sharedProfile must be a boolean`);
102
+ }
103
+ }
90
104
  return provider as MemoryProvider<ExtensionAPI>;
91
105
  }
92
106
 
107
+ /** provider 是否声明支持跨会话用户画像(C6)。缺省 = 不支持。 */
108
+ export function providerSupportsSharedProfile(provider: MemoryProvider<ExtensionAPI>): boolean {
109
+ return provider.capabilities?.sharedProfile === true;
110
+ }
111
+
93
112
  /**
94
113
  * 注册一个提供方。
95
114
  *
package/src/session.ts CHANGED
@@ -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 { 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";
@@ -491,6 +491,20 @@ export function compileSystemPrompt(
491
491
  */
492
492
  const memorySessionsByAgent = new WeakMap<AgentSession, MemoryProviderSession<ExtensionAPI>>();
493
493
 
494
+ /**
495
+ * 产品依赖跨会话画像,但选中的 provider 没声明该能力时给宿主的可读告警(C6)。
496
+ * 导出为纯函数,便于契约测试钉住文案;返回 null 表示无需告警。
497
+ */
498
+ export function sharedProfileMismatchWarning(
499
+ requiresSharedProfile: boolean,
500
+ providerSupports: boolean,
501
+ ): string | null {
502
+ if (!requiresSharedProfile || providerSupports) return null;
503
+ return "此产品声明依赖跨会话用户画像(agent.memory.requiresSharedProfile),"
504
+ + "但所选记忆 provider 未声明支持该能力(capabilities.sharedProfile);"
505
+ + "用户偏好不会在 scope 之间共享。请改用支持该能力的 provider,或移除该依赖声明。";
506
+ }
507
+
494
508
  /**
495
509
  * Build a pi session locked down for multi-user serving:
496
510
  * - no built-in tools (no bash / read / write / edit), verified by test
@@ -615,8 +629,21 @@ export async function createProductSession(opts: CreateProductSessionOptions): P
615
629
  // Two disjoint roots per session: the scope (user × product × qual) and the
616
630
  // user's cross-scope profile. Siblings, not nested — erasing one qualification
617
631
  // must not delete the user's identity, and the provider enforces that too.
618
- const memorySession = product.memoryEnabled
619
- ? await resolveMemoryProvider(product.memoryProviderId).open({
632
+ const memoryProvider = product.memoryEnabled
633
+ ? resolveMemoryProvider(product.memoryProviderId)
634
+ : null;
635
+ // C6: a product may declare it depends on cross-scope profile. If the chosen
636
+ // provider does not advertise that capability, warn instead of letting the
637
+ // capability silently disappear. Warning only — the session still opens.
638
+ if (memoryProvider) {
639
+ const warning = sharedProfileMismatchWarning(
640
+ product.requiresSharedProfile,
641
+ providerSupportsSharedProfile(memoryProvider),
642
+ );
643
+ if (warning) opts.onUINotify?.(warning, "warning");
644
+ }
645
+ const memorySession = memoryProvider
646
+ ? await memoryProvider.open({
620
647
  storageRoot: path.join(opts.dataDir, "memory", opts.userId, opts.qual || "default"),
621
648
  sharedRoot: path.join(opts.dataDir, "memory", opts.userId, "profile"),
622
649
  agentDir: opts.dataDir,