@hyperspell/openclaw-hyperspell 0.10.0 → 0.11.0

package/client.ts

@@ -1,5 +1,10 @@
 import Hyperspell from "hyperspell";
-import type { HyperspellConfig, HyperspellSource } from "./config.ts";
+import type {
+	HyperspellConfig,
+	HyperspellSource,
+	ScopeName,
+} from "./config.ts";
+import { normalizeScope } from "./config.ts";
 import { log } from "./logger.ts";
 
 export type Highlight = {
@@ -95,6 +100,7 @@ export class HyperspellClient {
 			after?: string;
 			before?: string;
 			userId?: string;
+			filter?: Record<string, unknown>;
 		},
 	): Promise<SearchResult[]> {
 		const limit = options?.limit ?? this.config.maxResults;
@@ -109,6 +115,7 @@ export class HyperspellClient {
 			after: options?.after,
 			before: options?.before,
 			userId: options?.userId,
+			filter: options?.filter,
 		});
 
 		const response = await this.client.memories.search(
@@ -119,6 +126,7 @@ export class HyperspellClient {
 					max_results: limit,
 					...(options?.after ? { after: options.after } : {}),
 					...(options?.before ? { before: options.before } : {}),
+					...(options?.filter ? { filter: options.filter } : {}),
 				},
 			},
 			this.requestOptions(options?.userId),
@@ -155,6 +163,7 @@ export class HyperspellClient {
 			after?: string;
 			before?: string;
 			userId?: string;
+			filter?: Record<string, unknown>;
 		},
 	): Promise<Record<string, unknown>> {
 		const limit = options?.limit ?? this.config.maxResults;
@@ -169,6 +178,7 @@ export class HyperspellClient {
 			after: options?.after,
 			before: options?.before,
 			userId: options?.userId,
+			filter: options?.filter,
 		});
 
 		const response = await this.client.memories.search(
@@ -179,6 +189,7 @@ export class HyperspellClient {
 					max_results: limit,
 					...(options?.after ? { after: options.after } : {}),
 					...(options?.before ? { before: options.before } : {}),
+					...(options?.filter ? { filter: options.filter } : {}),
 				},
 			},
 			this.requestOptions(options?.userId),
@@ -197,6 +208,7 @@ export class HyperspellClient {
 			limit?: number;
 			sources?: HyperspellSource[];
 			userId?: string;
+			filter?: Record<string, unknown>;
 		},
 	): Promise<SearchWithAnswerResult> {
 		const limit = options?.limit ?? this.config.maxResults;
@@ -209,6 +221,7 @@ export class HyperspellClient {
 			limit,
 			sources,
 			userId: options?.userId,
+			filter: options?.filter,
 		});
 
 		const response = await this.client.memories.search(
@@ -218,6 +231,7 @@ export class HyperspellClient {
 				answer: true,
 				options: {
 					max_results: limit,
+					...(options?.filter ? { filter: options.filter } : {}),
 				},
 			},
 			this.requestOptions(options?.userId),
@@ -253,6 +267,7 @@ export class HyperspellClient {
 			date?: string;
 			metadata?: Record<string, string | number | boolean>;
 			userId?: string;
+			scope?: ScopeName;
 		},
 	): Promise<{ resourceId: string }> {
 		log.debugRequest("memories.add", {
@@ -262,6 +277,7 @@ export class HyperspellClient {
 			collection: options?.collection,
 			date: options?.date,
 			userId: options?.userId,
+			scope: options?.scope,
 		});
 
 		const result = await this.client.memories.add(
@@ -272,8 +288,12 @@ export class HyperspellClient {
 				collection: options?.collection,
 				date: options?.date,
 				metadata: {
-					...options?.metadata,
 					openclaw_source: "command",
+					...options?.metadata,
+					...(options?.userId ? { openclaw_user: options.userId } : {}),
+					...(options?.scope
+						? { openclaw_scope: normalizeScope(options.scope) }
+						: {}),
 				},
 			},
 			this.requestOptions(options?.userId),
@@ -380,6 +400,7 @@ export class HyperspellClient {
 			extract?: Array<"procedure" | "memory" | "mood">;
 			metadata?: Record<string, string | number | boolean>;
 			userId?: string;
+			scope?: ScopeName;
 		},
 	): Promise<{ resourceId: string; status: string }> {
 		log.debugRequest("sessions.add", {
@@ -387,6 +408,7 @@ export class HyperspellClient {
 			sessionId: options?.sessionId,
 			extract: options?.extract,
 			userId: options?.userId,
+			scope: options?.scope,
 		});
 
 		const result = await this.client.sessions.add(
@@ -402,8 +424,12 @@ export class HyperspellClient {
 					"procedure" | "memory"
 				>,
 				metadata: {
-					...options?.metadata,
 					openclaw_source: "agent_end",
+					...options?.metadata,
+					...(options?.userId ? { openclaw_user: options.userId } : {}),
+					...(options?.scope
+						? { openclaw_scope: normalizeScope(options.scope) }
+						: {}),
 				},
 			},
 			this.requestOptions(options?.userId),

package/commands/slash.ts

@@ -1,11 +1,29 @@
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
 import type { HyperspellClient } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
+import type { CanReadScope, HyperspellConfig } from "../config.ts"
 import { getWorkspaceDir } from "../config.ts"
-import { resolveUser } from "../lib/sender.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  getDefaultWriteScope,
+  resolveRole,
+  resolveUser,
+  routeWrite,
+} from "../lib/sender.ts"
 import { log } from "../logger.ts"
 import { syncAllMemoryFiles } from "../sync/markdown.ts"
 
+/**
+ * Strip a `#scope-name` prefix from free text. Returns the scope and the
+ * remainder. Used by /remember and /getcontext to let users narrow or route
+ * via a single keystroke.
+ */
+function parseScopePrefix(text: string): { scope?: string; rest: string } {
+  const m = text.match(/^#(\S+)\s+(.*)$/)
+  if (!m) return { rest: text }
+  return { scope: m[1], rest: m[2] }
+}
+
 function truncate(text: string, maxLength: number): string {
   if (text.length <= maxLength) return text
   return `${text.slice(0, maxLength)}…`
@@ -28,17 +46,33 @@ export function registerCommands(
     acceptsArgs: true,
     requireAuth: true,
     handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
-      const query = ctx.args?.trim()
-      if (!query) {
-        return { text: "Usage: /getcontext <search query>" }
+      const rawArgs = ctx.args?.trim()
+      if (!rawArgs) {
+        return { text: "Usage: /getcontext [#scope] <search query>" }
       }
+      const { scope: requestedScope, rest: query } = parseScopePrefix(rawArgs)
 
       const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
       const userId = resolved?.userId
-      log.debug(`/getcontext command: "${query}" userId=${userId}`)
+
+      // Build scope filter: intersect requested scope (if any) with caller's canRead.
+      let filter: Record<string, unknown> | undefined
+      if (cfg.multiUser?.scoping) {
+        const canRead = getCanReadScopes(resolved, cfg)
+        const allowed: CanReadScope[] = requestedScope
+          ? canRead.includes("*") || canRead.includes(requestedScope)
+            ? [requestedScope]
+            : []
+          : canRead
+        filter = buildScopeFilter(allowed, resolved?.userId ?? "")
+      }
+
+      log.debug(
+        `/getcontext command: "${query}" userId=${userId} scope=${requestedScope ?? "any"}`,
+      )
 
       try {
-        const results = await client.search(query, { limit: 5, userId })
+        const results = await client.search(query, { limit: 5, userId, filter })
 
         if (results.length === 0) {
           return { text: `No memories found for: "${query}"` }
@@ -67,23 +101,60 @@ export function registerCommands(
     acceptsArgs: true,
     requireAuth: true,
     handler: async (ctx: { args?: string; senderId?: string; channel?: string }) => {
-      const text = ctx.args?.trim()
-      if (!text) {
-        return { text: "Usage: /remember <text to remember>" }
+      const rawArgs = ctx.args?.trim()
+      if (!rawArgs) {
+        return { text: "Usage: /remember [#scope] <text to remember>" }
       }
+      const { scope: requestedScope, rest: text } = parseScopePrefix(rawArgs)
 
       const resolved = resolveUser(ctx as Record<string, unknown>, cfg)
-      const userId = resolved?.userId
-      log.debug(`/remember command: "${truncate(text, 50)}" userId=${userId}`)
+      const scopingEnabled = !!cfg.multiUser?.scoping
+      const availableScopes = cfg.multiUser?.scoping?.scopes ?? []
+
+      // Scope resolution: prefix > role default > global default > "private"
+      const scope = scopingEnabled
+        ? (requestedScope ?? getDefaultWriteScope(resolved, cfg))
+        : "private"
+
+      // Validate scope is in declared vocabulary
+      if (
+        scopingEnabled &&
+        requestedScope &&
+        availableScopes.length > 0 &&
+        !availableScopes.includes(scope)
+      ) {
+        return {
+          text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
+        }
+      }
+
+      // canWriteScopes enforcement
+      if (scopingEnabled) {
+        const role = resolveRole(resolved, cfg)
+        if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
+          return { text: `You cannot write to scope "${scope}".` }
+        }
+      }
+
+      const { userId, collection } = scopingEnabled
+        ? routeWrite(resolved, scope, cfg)
+        : { userId: resolved?.userId, collection: undefined }
+
+      log.debug(
+        `/remember command: "${truncate(text, 50)}" userId=${userId} scope=${scope}`,
+      )
 
       try {
         await client.addMemory(text, {
           metadata: { source: "openclaw_command" },
+          collection,
           userId,
+          scope: scopingEnabled ? scope : undefined,
         })
 
         const preview = truncate(text, 60)
-        return { text: `Remembered: "${preview}"` }
+        const scopeHint = scopingEnabled ? ` [${scope}]` : ""
+        return { text: `Remembered${scopeHint}: "${preview}"` }
       } catch (err) {
         log.error("/remember failed", err)
         return { text: "Failed to save memory. Check logs for details." }

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

@@ -29,14 +29,51 @@ 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;
@@ -149,6 +186,130 @@ 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>;
@@ -164,6 +325,7 @@ function parseMultiUser(raw: unknown): MultiUserConfig | undefined {
 						userId: p.userId,
 						name: p.name,
 						context: typeof p.context === "string" ? p.context : undefined,
+						role: typeof p.role === "string" ? p.role : undefined,
 					};
 				}
 			}
@@ -180,6 +342,7 @@ function parseMultiUser(raw: unknown): MultiUserConfig | undefined {
 			typeof mu.includeSharedInSearch === "boolean"
 				? mu.includeSharedInSearch
 				: true,
+		scoping: parseScoping(mu.scoping),
 	};
 }