@hyperspell/openclaw-hyperspell 0.9.0 → 0.11.0

package/config.test.ts

@@ -0,0 +1,202 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import { parseConfig } from "./config.ts"
+
+const base = {
+  apiKey: "test-key",
+  userId: "u1",
+}
+
+test("parseConfig — no multiUser returns no scoping", () => {
+  const cfg = parseConfig(base)
+  assert.equal(cfg.multiUser, undefined)
+})
+
+test("parseConfig — multiUser without scoping is valid", () => {
+  const cfg = parseConfig({
+    ...base,
+    multiUser: {
+      senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+      sharedUserId: "shared",
+    },
+  })
+  assert.equal(cfg.multiUser?.scoping, undefined)
+  assert.equal(cfg.multiUser?.sharedUserId, "shared")
+})
+
+test("parseConfig — scoping disabled returns no scoping", () => {
+  const cfg = parseConfig({
+    ...base,
+    multiUser: {
+      senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+      scoping: {
+        enabled: false,
+        defaultScope: "private",
+        scopes: ["private"],
+        roles: {},
+        users: {},
+      },
+    },
+  })
+  assert.equal(cfg.multiUser?.scoping, undefined)
+})
+
+test("parseConfig — empty scopes array throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "private",
+            scopes: [],
+            roles: {},
+            users: {},
+          },
+        },
+      }),
+    /scoping\.scopes/,
+  )
+})
+
+test("parseConfig — defaultScope not in scopes throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "nonexistent",
+            scopes: ["private", "family"],
+            roles: {},
+            users: {},
+          },
+        },
+      }),
+    /defaultScope/,
+  )
+})
+
+test("parseConfig — role canRead with unknown scope throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "private",
+            scopes: ["private", "family"],
+            roles: {
+              weird: { canRead: ["private", "ghost"], defaultWriteScope: "private" },
+            },
+            users: {},
+          },
+        },
+      }),
+    /canRead.*ghost/,
+  )
+})
+
+test("parseConfig — role defaultWriteScope not in scopes throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "private",
+            scopes: ["private", "family"],
+            roles: {
+              weird: { canRead: ["family"], defaultWriteScope: "nonexistent" },
+            },
+            users: {},
+          },
+        },
+      }),
+    /defaultWriteScope/,
+  )
+})
+
+test("parseConfig — canWriteScopes with unknown scope throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "private",
+            scopes: ["private", "family"],
+            roles: {
+              weird: {
+                canRead: ["*"],
+                defaultWriteScope: "private",
+                canWriteScopes: ["ghost"],
+              },
+            },
+            users: {},
+          },
+        },
+      }),
+    /canWriteScopes.*ghost/,
+  )
+})
+
+test("parseConfig — user role keying into unknown role throws", () => {
+  assert.throws(
+    () =>
+      parseConfig({
+        ...base,
+        multiUser: {
+          senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+          scoping: {
+            enabled: true,
+            defaultScope: "private",
+            scopes: ["private", "family"],
+            roles: {
+              parent: { canRead: ["*"], defaultWriteScope: "private" },
+            },
+            users: { u1: { role: "nonexistent" } },
+          },
+        },
+      }),
+    /does not key into scoping\.roles/,
+  )
+})
+
+test("parseConfig — valid scoping parses", () => {
+  const cfg = parseConfig({
+    ...base,
+    multiUser: {
+      senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+      scoping: {
+        enabled: true,
+        defaultScope: "private",
+        scopes: ["private", "family", "parent_only"],
+        roles: {
+          parent: { canRead: ["*"], defaultWriteScope: "private" },
+          kid: { canRead: ["family"], defaultWriteScope: "family" },
+        },
+        users: {
+          u1: { role: "parent" },
+        },
+        collections: { family: "household" },
+        voiceId: { enabled: true, confidenceThreshold: 0.8 },
+      },
+    },
+  })
+  assert.equal(cfg.multiUser?.scoping?.enabled, true)
+  assert.deepEqual(cfg.multiUser?.scoping?.scopes, ["private", "family", "parent_only"])
+  assert.equal(cfg.multiUser?.scoping?.roles.parent?.defaultWriteScope, "private")
+  assert.equal(cfg.multiUser?.scoping?.collections?.family, "household")
+  assert.equal(cfg.multiUser?.scoping?.voiceId?.confidenceThreshold, 0.8)
+})

package/config.ts

@@ -25,6 +25,55 @@ export type AutoTraceConfig = {
 	metadata?: Record<string, string | number | boolean>;
 };
 
+export type UserProfile = {
+	userId: string;
+	name: string;
+	context?: string;
+	role?: string;
+};
+
+export type ScopeName = string;
+export type CanReadScope = ScopeName | "*" | "self";
+
+export type Role = {
+	canRead: CanReadScope[];
+	defaultWriteScope: ScopeName;
+	canWriteScopes?: ScopeName[];
+};
+
+export type VoiceIdConfig = {
+	enabled: boolean;
+	adapter?: string;
+	confidenceThreshold?: number;
+};
+
+export type ScopingConfig = {
+	enabled: boolean;
+	defaultScope: ScopeName;
+	scopes: ScopeName[];
+	roles: Record<string, Role>;
+	users: Record<string, { role: string }>;
+	collections?: Record<ScopeName, string>;
+	voiceId?: VoiceIdConfig;
+};
+
+export type MultiUserConfig = {
+	senderMap: Record<string, UserProfile>;
+	sharedUserId: string;
+	includeSharedInSearch: boolean;
+	scoping?: ScopingConfig;
+};
+
+/**
+ * Convert user-facing scope names (which may contain hyphens) to SDK-safe
+ * metadata values (alphanumeric + underscore only). Must be applied at every
+ * boundary where scopes cross into Hyperspell metadata — writes and reads —
+ * or filters will silently miss.
+ */
+export function normalizeScope(scope: ScopeName): string {
+	return scope.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+
 export type HyperspellConfig = {
 	apiKey: string;
 	userId?: string;
@@ -38,6 +87,7 @@ export type HyperspellConfig = {
 	relevanceThreshold: number;
 	debug: boolean;
 	knowledgeGraph: KnowledgeGraphConfig;
+	multiUser?: MultiUserConfig;
 };
 
 const ALLOWED_KEYS = [
@@ -53,6 +103,7 @@ const ALLOWED_KEYS = [
 	"relevanceThreshold",
 	"debug",
 	"knowledgeGraph",
+	"multiUser",
 ];
 
 const VALID_SOURCES: HyperspellSource[] = [
@@ -135,6 +186,166 @@ function parseSources(raw: string | string[] | undefined): HyperspellSource[] {
 	return sources;
 }
 
+function parseScoping(raw: unknown): ScopingConfig | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const sc = raw as Record<string, unknown>;
+
+	if (sc.enabled !== true) return undefined;
+
+	const scopes = Array.isArray(sc.scopes)
+		? (sc.scopes.filter((s) => typeof s === "string") as ScopeName[])
+		: [];
+	if (scopes.length === 0) {
+		throw new Error("scoping.scopes must be a non-empty array of scope names");
+	}
+
+	const defaultScope =
+		typeof sc.defaultScope === "string" ? sc.defaultScope : "private";
+	if (!scopes.includes(defaultScope)) {
+		throw new Error(
+			`scoping.defaultScope "${defaultScope}" must be one of scopes: ${scopes.join(", ")}`,
+		);
+	}
+
+	const rolesRaw =
+		sc.roles && typeof sc.roles === "object"
+			? (sc.roles as Record<string, unknown>)
+			: {};
+	const roles: Record<string, Role> = {};
+	for (const [roleName, rRaw] of Object.entries(rolesRaw)) {
+		if (!rRaw || typeof rRaw !== "object") continue;
+		const r = rRaw as Record<string, unknown>;
+
+		const canRead = Array.isArray(r.canRead)
+			? (r.canRead.filter((s) => typeof s === "string") as CanReadScope[])
+			: [];
+		for (const s of canRead) {
+			if (s === "*" || s === "self") continue;
+			if (!scopes.includes(s)) {
+				throw new Error(
+					`scoping.roles.${roleName}.canRead contains unknown scope "${s}"`,
+				);
+			}
+		}
+
+		const defaultWriteScope =
+			typeof r.defaultWriteScope === "string"
+				? r.defaultWriteScope
+				: defaultScope;
+		if (!scopes.includes(defaultWriteScope)) {
+			throw new Error(
+				`scoping.roles.${roleName}.defaultWriteScope "${defaultWriteScope}" must be one of scopes: ${scopes.join(", ")}`,
+			);
+		}
+
+		let canWriteScopes: ScopeName[] | undefined;
+		if (Array.isArray(r.canWriteScopes)) {
+			canWriteScopes = r.canWriteScopes.filter(
+				(s): s is ScopeName => typeof s === "string",
+			);
+			for (const s of canWriteScopes) {
+				if (!scopes.includes(s)) {
+					throw new Error(
+						`scoping.roles.${roleName}.canWriteScopes contains unknown scope "${s}"`,
+					);
+				}
+			}
+		}
+
+		roles[roleName] = { canRead, defaultWriteScope, canWriteScopes };
+	}
+
+	const usersRaw =
+		sc.users && typeof sc.users === "object"
+			? (sc.users as Record<string, unknown>)
+			: {};
+	const users: Record<string, { role: string }> = {};
+	for (const [uid, uRaw] of Object.entries(usersRaw)) {
+		if (!uRaw || typeof uRaw !== "object") continue;
+		const u = uRaw as Record<string, unknown>;
+		if (typeof u.role !== "string") continue;
+		if (!roles[u.role]) {
+			throw new Error(
+				`scoping.users.${uid}.role "${u.role}" does not key into scoping.roles`,
+			);
+		}
+		users[uid] = { role: u.role };
+	}
+
+	const collectionsRaw =
+		sc.collections && typeof sc.collections === "object"
+			? (sc.collections as Record<string, unknown>)
+			: undefined;
+	let collections: Record<ScopeName, string> | undefined;
+	if (collectionsRaw) {
+		collections = {};
+		for (const [scopeName, coll] of Object.entries(collectionsRaw)) {
+			if (typeof coll === "string" && scopes.includes(scopeName)) {
+				collections[scopeName] = coll;
+			}
+		}
+	}
+
+	let voiceId: VoiceIdConfig | undefined;
+	if (sc.voiceId && typeof sc.voiceId === "object") {
+		const v = sc.voiceId as Record<string, unknown>;
+		voiceId = {
+			enabled: v.enabled === true,
+			adapter: typeof v.adapter === "string" ? v.adapter : undefined,
+			confidenceThreshold:
+				typeof v.confidenceThreshold === "number"
+					? v.confidenceThreshold
+					: undefined,
+		};
+	}
+
+	return {
+		enabled: true,
+		defaultScope,
+		scopes,
+		roles,
+		users,
+		collections,
+		voiceId,
+	};
+}
+
+function parseMultiUser(raw: unknown): MultiUserConfig | undefined {
+	if (!raw || typeof raw !== "object") return undefined;
+	const mu = raw as Record<string, unknown>;
+
+	const senderMap: Record<string, UserProfile> = {};
+	const rawMap = mu.senderMap as Record<string, unknown> | undefined;
+	if (rawMap && typeof rawMap === "object") {
+		for (const [handle, profile] of Object.entries(rawMap)) {
+			if (profile && typeof profile === "object") {
+				const p = profile as Record<string, unknown>;
+				if (typeof p.userId === "string" && typeof p.name === "string") {
+					senderMap[handle] = {
+						userId: p.userId,
+						name: p.name,
+						context: typeof p.context === "string" ? p.context : undefined,
+						role: typeof p.role === "string" ? p.role : undefined,
+					};
+				}
+			}
+		}
+	}
+
+	if (Object.keys(senderMap).length === 0) return undefined;
+
+	return {
+		senderMap,
+		sharedUserId:
+			typeof mu.sharedUserId === "string" ? mu.sharedUserId : "shared",
+		includeSharedInSearch:
+			typeof mu.includeSharedInSearch === "boolean"
+				? mu.includeSharedInSearch
+				: true,
+		scoping: parseScoping(mu.scoping),
+	};
+}
+
 export function parseConfig(raw: unknown): HyperspellConfig {
 	const cfg =
 		raw && typeof raw === "object" && !Array.isArray(raw)
@@ -184,6 +395,7 @@ export function parseConfig(raw: unknown): HyperspellConfig {
 			scanIntervalMinutes: (kgRaw.scanIntervalMinutes as number) ?? 60,
 			batchSize: (kgRaw.batchSize as number) ?? 20,
 		},
+		multiUser: parseMultiUser(cfg.multiUser),
 	};
 }
 

package/graph/ops.ts

@@ -1,6 +1,8 @@
 import * as fs from "node:fs"
 import * as path from "node:path"
 import type { HyperspellClient } from "../client.ts"
+import type { HyperspellConfig } from "../config.ts"
+import { getAllUserIds } from "../lib/sender.ts"
 import { log } from "../logger.ts"
 import { NetworkStateManager } from "./state.ts"
 
@@ -93,38 +95,42 @@ export async function scanMemories(
   client: HyperspellClient,
   stateManager: NetworkStateManager,
   batchSize: number,
+  cfg?: HyperspellConfig,
 ): Promise<ScannedMemory[]> {
   const unprocessed: ScannedMemory[] = []
+  const userIds = cfg ? getAllUserIds(cfg) : [undefined]
+
+  outer: for (const userId of userIds) {
+    for await (const mem of client.listMemories({ userId })) {
+      if (stateManager.isProcessed(mem.resourceId)) continue
+      if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true) continue
+      if ((mem.metadata?.status as string) !== "completed") continue
+
+      let summary = ""
+      try {
+        const full = await client.getMemory(mem.resourceId, mem.source as import("../config.ts").HyperspellSource, { userId })
+        const data = full.data as unknown[] | undefined
+
+        const participants = full.participants as Array<{ name?: string; email?: string }> | undefined
+        const participantLine = participants?.length
+          ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
+          : ""
+
+        const dataSummary = data ? summarizeMemoryData(data, mem.source) : ""
+        summary = [participantLine, dataSummary].filter(Boolean).join("\n\n")
+      } catch {
+        summary = "(content unavailable)"
+      }
 
-  for await (const mem of client.listMemories()) {
-    if (stateManager.isProcessed(mem.resourceId)) continue
-    if (mem.metadata?.graph_entity === "true" || mem.metadata?.graph_entity === true) continue
-    if ((mem.metadata?.status as string) !== "completed") continue
-
-    let summary = ""
-    try {
-      const full = await client.getMemory(mem.resourceId, mem.source)
-      const data = full.data as unknown[] | undefined
-
-      const participants = full.participants as Array<{ name?: string; email?: string }> | undefined
-      const participantLine = participants?.length
-        ? `Participants: ${participants.map((p) => `${p.name || ""} <${p.email || ""}>`).join(", ")}`
-        : ""
-
-      const dataSummary = data ? summarizeMemoryData(data, mem.source) : ""
-      summary = [participantLine, dataSummary].filter(Boolean).join("\n\n")
-    } catch {
-      summary = "(content unavailable)"
-    }
+      unprocessed.push({
+        resourceId: mem.resourceId,
+        source: mem.source,
+        title: mem.title,
+        summary: summary.slice(0, 1000),
+      })
 
-    unprocessed.push({
-      resourceId: mem.resourceId,
-      source: mem.source,
-      title: mem.title,
-      summary: summary.slice(0, 1000),
-    })
-
-    if (unprocessed.length >= batchSize) break
+      if (unprocessed.length >= batchSize) break outer
+    }
   }
 
   return unprocessed

package/graph/tools.ts

@@ -32,7 +32,7 @@ export function registerNetworkTools(
       async execute(_toolCallId: string, params: { batchSize?: number }) {
         const batchSize = params.batchSize ?? cfg.knowledgeGraph.batchSize
         try {
-          const memories = await scanMemories(client, stateManager, batchSize)
+          const memories = await scanMemories(client, stateManager, batchSize, cfg)
           const text = formatScanResults(memories, stateManager.getProcessedCount(), stateManager.getLastScanAt())
           return {
             content: [{ type: "text" as const, text }],