@hyperspell/openclaw-hyperspell 0.10.0 → 0.11.0

package/hooks/auto-context.ts

@@ -1,6 +1,11 @@
 import type { HyperspellClient, SearchResult } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
-import { resolveUser } from "../lib/sender.ts"
+import type { CanReadScope, HyperspellConfig } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  resolveUser,
+  type ResolvedUser,
+} from "../lib/sender.ts"
 import { log } from "../logger.ts"
 
 function formatRelativeTime(isoTimestamp: string): string {
@@ -111,16 +116,24 @@ async function multiUserSearch(
   client: HyperspellClient,
   cfg: HyperspellConfig,
   prompt: string,
-  resolved:
-    | { userId: string; name: string; context?: string; resolved: boolean }
-    | undefined,
+  resolved: ResolvedUser | undefined,
 ) {
   const multiUser = cfg.multiUser!
   const isKnownSender = !!resolved?.resolved
   const includeShared = multiUser.includeSharedInSearch
 
+  // Determine scope filter for the shared-space search based on caller's role.
+  // Unknown senders fall back to least-sensitive scopes; absent scoping config →
+  // filter is undefined → PR #6 behavior preserved.
+  const canRead: CanReadScope[] = multiUser.scoping
+    ? isKnownSender
+      ? getCanReadScopes(resolved, cfg)
+      : ["family", "kid_shared"]
+    : ["*"]
+  const scopeFilter = buildScopeFilter(canRead, resolved?.userId ?? "")
+
   log.debug(
-    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"}`,
+    `auto-context: searching for "${prompt.slice(0, 50)}..." user=${resolved?.userId ?? "unknown"} canRead=${JSON.stringify(canRead)}`,
   )
 
   // Build parallel searches — personal (known senders only) + shared
@@ -140,6 +153,7 @@ async function multiUserSearch(
       ? client.search(prompt, {
           limit: sharedLimit,
           userId: multiUser.sharedUserId,
+          filter: scopeFilter,
         })
       : null
 

package/hooks/auto-trace.ts

@@ -125,6 +125,10 @@ export function buildAutoTraceHandler(
 				extract: cfg.autoTrace.extract,
 				metadata: cfg.autoTrace.metadata,
 				userId,
+				// Auto-trace captures full conversation text — the most sensitive class
+				// of memory. Default to private; users opt into family-visible recall
+				// via explicit /remember.
+				scope: "private",
 			});
 			log.info(
 				`auto-trace: sent ${result.resourceId} (${messages.length} messages${userId ? `, user=${userId}` : ""})`,

package/lib/sender.test.ts

@@ -0,0 +1,234 @@
+import assert from "node:assert/strict"
+import { test } from "node:test"
+import type { HyperspellConfig } from "../config.ts"
+import {
+  buildScopeFilter,
+  getCanReadScopes,
+  getDefaultWriteScope,
+  resolveRole,
+  routeWrite,
+} from "./sender.ts"
+
+function cfg(overrides: Partial<HyperspellConfig["multiUser"]> = {}): HyperspellConfig {
+  return {
+    apiKey: "test",
+    autoContext: false,
+    autoTrace: { enabled: false, extract: ["procedure"] },
+    emotionalContext: false,
+    syncMemories: false,
+    sources: [],
+    maxResults: 5,
+    relevanceThreshold: 0.6,
+    debug: false,
+    knowledgeGraph: { enabled: false, scanIntervalMinutes: 60, batchSize: 20 },
+    multiUser: overrides.scoping
+      ? {
+          sharedUserId: "shared",
+          includeSharedInSearch: true,
+          senderMap: overrides.senderMap ?? {},
+          scoping: overrides.scoping,
+        }
+      : undefined,
+  }
+}
+
+test("buildScopeFilter — wildcard returns undefined", () => {
+  assert.equal(buildScopeFilter(["*"], "u1"), undefined)
+})
+
+test("buildScopeFilter — empty returns match-nothing filter (not undefined)", () => {
+  const f = buildScopeFilter([], "u1")
+  assert.deepEqual(f, { openclaw_scope: "__never__" })
+})
+
+test("buildScopeFilter — single named scope collapses $or", () => {
+  const f = buildScopeFilter(["family"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["family"] } })
+})
+
+test("buildScopeFilter — multiple named scopes", () => {
+  const f = buildScopeFilter(["family", "kid_shared"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["family", "kid_shared"] } })
+})
+
+test("buildScopeFilter — scopes plus self produces $or", () => {
+  const f = buildScopeFilter(["family", "self"], "u1")
+  assert.deepEqual(f, {
+    $or: [
+      { openclaw_scope: { $in: ["family"] } },
+      { openclaw_user: "u1" },
+    ],
+  })
+})
+
+test("buildScopeFilter — hyphenated scope normalized in metadata", () => {
+  const f = buildScopeFilter(["parent-only"], "u1")
+  assert.deepEqual(f, { openclaw_scope: { $in: ["parent_only"] } })
+})
+
+test("buildScopeFilter — self only (no named scopes)", () => {
+  const f = buildScopeFilter(["self"], "u1")
+  assert.deepEqual(f, { openclaw_user: "u1" })
+})
+
+test("buildScopeFilter — self only with empty userId → match-nothing", () => {
+  const f = buildScopeFilter(["self"], "")
+  // Empty userId cannot build a self clause; no named scopes either → match-nothing
+  assert.deepEqual(f, { openclaw_scope: "__never__" })
+})
+
+test("getCanReadScopes — scoping absent returns wildcard", () => {
+  const c = cfg()
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, ["*"])
+})
+
+test("getCanReadScopes — role from scoping.users", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, ["family"])
+})
+
+test("getCanReadScopes — missing role returns empty (no access)", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: {}, // u1 has no role assignment
+    },
+  })
+  const canRead = getCanReadScopes(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.deepEqual(canRead, [])
+})
+
+test("getDefaultWriteScope — role default wins", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(scope, "family")
+})
+
+test("getDefaultWriteScope — falls back to global default when no role", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {},
+      users: {},
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(scope, "private")
+})
+
+test("getDefaultWriteScope — profile-level role override", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1", role: "parent" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: {
+        parent: { canRead: ["*"], defaultWriteScope: "private" },
+        kid: { canRead: ["family"], defaultWriteScope: "family" },
+      },
+      users: { u1: { role: "kid" } }, // users table says kid but profile override is parent
+    },
+  })
+  const scope = getDefaultWriteScope(
+    { userId: "u1", name: "U1", resolved: true, role: "parent" },
+    c,
+  )
+  assert.equal(scope, "private")
+})
+
+test("resolveRole — returns undefined when scoping absent", () => {
+  const c = cfg()
+  const role = resolveRole(
+    { userId: "u1", name: "U1", resolved: true },
+    c,
+  )
+  assert.equal(role, undefined)
+})
+
+test("routeWrite — private goes to user's own space", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: { kid: { canRead: ["family"], defaultWriteScope: "family" } },
+      users: { u1: { role: "kid" } },
+    },
+  })
+  const r = routeWrite(
+    { userId: "u1", name: "U1", resolved: true },
+    "private",
+    c,
+  )
+  assert.deepEqual(r, { userId: "u1", collection: undefined })
+})
+
+test("routeWrite — non-private goes to sharedUserId with optional collection", () => {
+  const c = cfg({
+    senderMap: { "u1-phone": { userId: "u1", name: "U1" } },
+    scoping: {
+      enabled: true,
+      defaultScope: "private",
+      scopes: ["private", "family"],
+      roles: { kid: { canRead: ["family"], defaultWriteScope: "family" } },
+      users: { u1: { role: "kid" } },
+      collections: { family: "household-shared" },
+    },
+  })
+  const r = routeWrite(
+    { userId: "u1", name: "U1", resolved: true },
+    "family",
+    c,
+  )
+  assert.deepEqual(r, { userId: "shared", collection: "household-shared" })
+})

package/lib/sender.ts

@@ -1,50 +1,56 @@
-import type { HyperspellConfig } from "../config.ts"
+import type {
+  CanReadScope,
+  HyperspellConfig,
+  Role,
+  ScopeName,
+} from "../config.ts"
+import { normalizeScope } from "../config.ts"
 import { log } from "../logger.ts"
+import { getVoiceIdentifier } from "./voice-id.ts"
 
 export interface ResolvedUser {
   userId: string
   name: string
   context?: string
+  /** Profile-level role override from senderMap. Falls back to scoping.users[userId].role. */
+  role?: string
   /** True if the sender was matched in senderMap; false if falling back to sharedUserId */
   resolved: boolean
 }
 
-/**
- * Resolve the sender's Hyperspell user from hook or tool context.
- *
- * Matches sender handles in the multiUser.senderMap against the sessionKey
- * using substring matching. Handles are sorted longest-first to prevent
- * partial matches (e.g., Discord ID "123" matching inside "1234567").
- *
- * Falls back to sharedUserId for unrecognized senders.
- */
-export function resolveUser(
+function matchFromSenderMap(
   ctx: Record<string, unknown> | undefined,
   cfg: HyperspellConfig,
 ): ResolvedUser | undefined {
   const multiUser = cfg.multiUser
   if (!multiUser) {
-    // Single-user mode: return config.userId if set
-    return cfg.userId ? { userId: cfg.userId, name: cfg.userId, resolved: true } : undefined
+    return cfg.userId
+      ? { userId: cfg.userId, name: cfg.userId, resolved: true }
+      : undefined
   }
 
-  // Try direct senderId lookup (available in slash command contexts;
-  // tool factory contexts do NOT include senderId — they have sessionKey instead)
-  const senderId = (ctx?.senderId as string) ?? (ctx?.requesterSenderId as string) ?? undefined
+  // Try direct senderId lookup (slash command contexts)
+  const senderId =
+    (ctx?.senderId as string) ??
+    (ctx?.requesterSenderId as string) ??
+    undefined
   if (senderId && multiUser.senderMap[senderId]) {
     const profile = multiUser.senderMap[senderId]
     log.debug(`sender resolved via senderId: ${senderId} -> ${profile.userId}`)
     return { ...profile, resolved: true }
   }
 
-  // Try sessionKey substring matching (works in both hook and tool factory contexts)
+  // Try sessionKey substring matching (longest-first to avoid partial matches)
   const sessionKey = ctx?.sessionKey as string | undefined
   if (sessionKey) {
-    const sortedEntries = Object.entries(multiUser.senderMap)
-      .sort(([a], [b]) => b.length - a.length)
+    const sortedEntries = Object.entries(multiUser.senderMap).sort(
+      ([a], [b]) => b.length - a.length,
+    )
     for (const [handle, profile] of sortedEntries) {
       if (sessionKey.includes(handle)) {
-        log.debug(`sender resolved via sessionKey: ${handle} -> ${profile.userId}`)
+        log.debug(
+          `sender resolved via sessionKey: ${handle} -> ${profile.userId}`,
+        )
         return { ...profile, resolved: true }
       }
     }
@@ -59,6 +65,52 @@ export function resolveUser(
   }
 }
 
+/**
+ * Synchronous sender resolution from sessionKey + senderMap. Use this for
+ * hooks and tools that don't receive audio — the voice-ID path is skipped.
+ */
+export function resolveUser(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): ResolvedUser | undefined {
+  return matchFromSenderMap(ctx, cfg)
+}
+
+/**
+ * Asynchronous sender resolution. Checks voice-ID first (if enabled and
+ * audio is in ctx), then falls back to the synchronous path. Callers that
+ * never receive audio should use `resolveUser` to avoid unnecessary async
+ * overhead.
+ */
+export async function resolveUserAsync(
+  ctx: Record<string, unknown> | undefined,
+  cfg: HyperspellConfig,
+): Promise<ResolvedUser | undefined> {
+  const voiceCfg = cfg.multiUser?.scoping?.voiceId
+  const audio = ctx?.audio as Buffer | string | undefined
+  if (voiceCfg?.enabled && audio && cfg.multiUser) {
+    try {
+      const identifier = getVoiceIdentifier(cfg)
+      const result = await identifier.identify(audio)
+      const threshold = voiceCfg.confidenceThreshold ?? 0.7
+      if (result && result.confidence >= threshold) {
+        // Find profile for the voice-identified userId
+        for (const profile of Object.values(cfg.multiUser.senderMap)) {
+          if (profile.userId === result.userId) {
+            log.debug(
+              `sender resolved via voice: ${result.userId} (conf=${result.confidence.toFixed(2)})`,
+            )
+            return { ...profile, resolved: true }
+          }
+        }
+      }
+    } catch (err) {
+      log.error("voice-id identification failed", err)
+    }
+  }
+  return matchFromSenderMap(ctx, cfg)
+}
+
 /**
  * Get all unique userIds from the multiUser config (for knowledge graph scanning).
  */
@@ -74,3 +126,109 @@ export function getAllUserIds(cfg: HyperspellConfig): string[] {
   userIds.add(cfg.multiUser.sharedUserId)
   return [...userIds]
 }
+
+/**
+ * Resolve the Role for a user. Looks first at the profile-level `role`
+ * override, then at `scoping.users[userId].role`. Returns undefined if
+ * scoping is disabled or the user has no role assignment.
+ */
+export function resolveRole(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): Role | undefined {
+  const scoping = cfg.multiUser?.scoping
+  if (!scoping || !user) return undefined
+  const roleName = user.role ?? scoping.users[user.userId]?.role
+  if (!roleName) return undefined
+  return scoping.roles[roleName]
+}
+
+/**
+ * Readable scopes for this user. If scoping is disabled, returns ["*"] so
+ * `buildScopeFilter` produces no filter and PR #6 behavior is preserved.
+ */
+export function getCanReadScopes(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): CanReadScope[] {
+  if (!cfg.multiUser?.scoping) return ["*"]
+  const role = resolveRole(user, cfg)
+  return role?.canRead ?? []
+}
+
+/**
+ * Default write scope for this user — explicit param > role default > global default.
+ */
+export function getDefaultWriteScope(
+  user: ResolvedUser | undefined,
+  cfg: HyperspellConfig,
+): ScopeName {
+  const role = resolveRole(user, cfg)
+  return (
+    role?.defaultWriteScope ??
+    cfg.multiUser?.scoping?.defaultScope ??
+    "private"
+  )
+}
+
+/**
+ * Build a MongoDB-style metadata filter for Hyperspell's `options.filter`.
+ *
+ * Contract:
+ * - `["*"]` (wildcard) → returns `undefined` (no filter).
+ * - `[]` (empty) → returns a **match-nothing** filter, NOT `undefined`. An
+ *   empty `canRead` is a deliberate "no access" signal and must not silently
+ *   return all results.
+ * - Otherwise: `$or` of named-scope clause and (if "self" present) an
+ *   own-user clause keyed by `openclaw_user`.
+ */
+export function buildScopeFilter(
+  canRead: CanReadScope[],
+  userId: string,
+): Record<string, unknown> | undefined {
+  if (canRead.includes("*")) return undefined
+  if (canRead.length === 0) {
+    // Deliberate "no access" — match nothing.
+    return { openclaw_scope: "__never__" }
+  }
+
+  const namedScopes = canRead.filter((s) => s !== "self" && s !== "*")
+  const includeSelf = canRead.includes("self")
+
+  const clauses: Array<Record<string, unknown>> = []
+  if (namedScopes.length > 0) {
+    clauses.push({
+      openclaw_scope: { $in: namedScopes.map((s) => normalizeScope(s)) },
+    })
+  }
+  if (includeSelf && userId) {
+    clauses.push({ openclaw_user: userId })
+  }
+
+  if (clauses.length === 0) {
+    return { openclaw_scope: "__never__" }
+  }
+  if (clauses.length === 1) {
+    return clauses[0]
+  }
+  return { $or: clauses }
+}
+
+/**
+ * Route a write: private scope stays in the user's own Hyperspell space
+ * (defense-in-depth); shared scopes go to `sharedUserId` with optional
+ * per-scope collection.
+ */
+export function routeWrite(
+  user: ResolvedUser | undefined,
+  scope: ScopeName,
+  cfg: HyperspellConfig,
+): { userId: string | undefined; collection: string | undefined } {
+  const scoping = cfg.multiUser?.scoping
+  if (scope === "private") {
+    return { userId: user?.userId, collection: undefined }
+  }
+  const sharedUserId = cfg.multiUser?.sharedUserId ?? user?.userId
+  const collection = scoping?.collections?.[scope]
+  return { userId: sharedUserId, collection }
+}

package/lib/voice-id.ts

@@ -0,0 +1,39 @@
+import type { HyperspellConfig } from "../config.ts"
+
+export interface VoiceIdResult {
+  userId: string
+  confidence: number
+}
+
+export interface VoiceIdentifier {
+  identify(audio: Buffer | string): Promise<VoiceIdResult | null>
+}
+
+const NO_OP: VoiceIdentifier = {
+  async identify() {
+    return null
+  },
+}
+
+const registry = new Map<string, VoiceIdentifier>()
+
+/**
+ * Register a voice-ID adapter implementation under a name that can be
+ * referenced from `cfg.multiUser.scoping.voiceId.adapter`. Call this from
+ * downstream code that wants to plug in a real speaker diarization model;
+ * Phase 1 ships with no adapters registered — the no-op is used.
+ */
+export function registerVoiceIdentifier(
+  name: string,
+  impl: VoiceIdentifier,
+): void {
+  registry.set(name, impl)
+}
+
+export function getVoiceIdentifier(cfg: HyperspellConfig): VoiceIdentifier {
+  const name = cfg.multiUser?.scoping?.voiceId?.adapter
+  if (name && registry.has(name)) {
+    return registry.get(name) as VoiceIdentifier
+  }
+  return NO_OP
+}

package/openclaw.plugin.json

@@ -64,6 +64,11 @@
 			"label": "Memory Network",
 			"help": "Extract entities (people, projects, orgs, topics) from memories into structured markdown files. Requires a cron job for periodic scanning.",
 			"advanced": true
+		},
+		"multiUser": {
+			"label": "Multi-User Support",
+			"help": "Per-sender context isolation for household or shared-device setups. Maps senders to user IDs; supports optional role-based privacy scopes (private/family/parent-only/etc).",
+			"advanced": true
 		}
 	},
 	"configSchema": {
@@ -124,6 +129,38 @@
 					},
 					"batchSize": { "type": "number", "minimum": 5, "maximum": 100 }
 				}
+			},
+			"multiUser": {
+				"type": "object",
+				"additionalProperties": true,
+				"properties": {
+					"senderMap": { "type": "object" },
+					"sharedUserId": { "type": "string" },
+					"includeSharedInSearch": { "type": "boolean" },
+					"scoping": {
+						"type": "object",
+						"additionalProperties": true,
+						"properties": {
+							"enabled": { "type": "boolean" },
+							"defaultScope": { "type": "string" },
+							"scopes": {
+								"type": "array",
+								"items": { "type": "string" }
+							},
+							"roles": { "type": "object" },
+							"users": { "type": "object" },
+							"collections": { "type": "object" },
+							"voiceId": {
+								"type": "object",
+								"properties": {
+									"enabled": { "type": "boolean" },
+									"adapter": { "type": "string" },
+									"confidenceThreshold": { "type": "number" }
+								}
+							}
+						}
+					}
+				}
 			}
 		},
 		"required": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperspell/openclaw-hyperspell",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "OpenClaw Hyperspell memory plugin",
   "license": "MIT",
@@ -42,7 +42,8 @@
   "scripts": {
     "check-types": "tsc --noEmit",
     "lint": "bunx @biomejs/biome ci .",
-    "lint:fix": "bunx @biomejs/biome check --write ."
+    "lint:fix": "bunx @biomejs/biome check --write .",
+    "test": "node --test --experimental-strip-types lib/sender.test.ts config.test.ts"
   },
   "openclaw": {
     "extensions": [