@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/lib/sender.ts

@@ -1,234 +0,0 @@
-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
-}
-
-function matchFromSenderMap(
-  ctx: Record<string, unknown> | undefined,
-  cfg: HyperspellConfig,
-): ResolvedUser | undefined {
-  const multiUser = cfg.multiUser
-  if (!multiUser) {
-    return cfg.userId
-      ? { userId: cfg.userId, name: cfg.userId, resolved: true }
-      : 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 (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,
-    )
-    for (const [handle, profile] of sortedEntries) {
-      if (sessionKey.includes(handle)) {
-        log.debug(
-          `sender resolved via sessionKey: ${handle} -> ${profile.userId}`,
-        )
-        return { ...profile, resolved: true }
-      }
-    }
-  }
-
-  // Fallback: use sharedUserId for unknown senders
-  log.debug("sender unresolved, falling back to sharedUserId")
-  return {
-    userId: multiUser.sharedUserId,
-    name: multiUser.sharedUserId,
-    resolved: false,
-  }
-}
-
-/**
- * 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).
- */
-export function getAllUserIds(cfg: HyperspellConfig): string[] {
-  if (!cfg.multiUser) {
-    return cfg.userId ? [cfg.userId] : []
-  }
-
-  const userIds = new Set<string>()
-  for (const profile of Object.values(cfg.multiUser.senderMap)) {
-    userIds.add(profile.userId)
-  }
-  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

@@ -1,39 +0,0 @@
-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/logger.ts

@@ -1,41 +0,0 @@
-type Logger = {
-  info: (message: string, ...args: unknown[]) => void
-  warn: (message: string, ...args: unknown[]) => void
-  error: (message: string, ...args: unknown[]) => void
-  debug: (message: string, ...args: unknown[]) => void
-}
-
-let _logger: Logger = console
-let _debug = false
-
-export function initLogger(logger: Logger, debug: boolean): void {
-  _logger = logger
-  _debug = debug
-}
-
-export const log = {
-  info: (message: string, ...args: unknown[]) => {
-    _logger.info(`hyperspell: ${message}`, ...args)
-  },
-  warn: (message: string, ...args: unknown[]) => {
-    _logger.warn(`hyperspell: ${message}`, ...args)
-  },
-  error: (message: string, ...args: unknown[]) => {
-    _logger.error(`hyperspell: ${message}`, ...args)
-  },
-  debug: (message: string, ...args: unknown[]) => {
-    if (_debug) {
-      _logger.debug(`hyperspell: ${message}`, ...args)
-    }
-  },
-  debugRequest: (method: string, params: unknown) => {
-    if (_debug) {
-      _logger.debug(`hyperspell: [${method}] request`, params)
-    }
-  },
-  debugResponse: (method: string, result: unknown) => {
-    if (_debug) {
-      _logger.debug(`hyperspell: [${method}] response`, result)
-    }
-  },
-}

package/sync/markdown.ts

@@ -1,186 +0,0 @@
-import * as fs from "node:fs"
-import * as path from "node:path"
-import type { HyperspellClient } from "../client.ts"
-import { log } from "../logger.ts"
-
-const FRONTMATTER_REGEX = /^---\n([\s\S]*?)\n---\n?/
-
-interface MarkdownFile {
-  filePath: string
-  title: string
-  content: string
-  hyperspellId: string | null
-}
-
-/**
- * Parse frontmatter from markdown content
- */
-function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
-  const match = content.match(FRONTMATTER_REGEX)
-  if (!match) {
-    return { frontmatter: {}, body: content }
-  }
-
-  const frontmatterText = match[1]
-  const body = content.slice(match[0].length)
-  const frontmatter: Record<string, string> = {}
-
-  for (const line of frontmatterText.split("\n")) {
-    const colonIndex = line.indexOf(":")
-    if (colonIndex > 0) {
-      const key = line.slice(0, colonIndex).trim()
-      const value = line.slice(colonIndex + 1).trim()
-      frontmatter[key] = value
-    }
-  }
-
-  return { frontmatter, body }
-}
-
-/**
- * Serialize frontmatter back to string
- */
-function serializeFrontmatter(frontmatter: Record<string, string>): string {
-  const lines = Object.entries(frontmatter).map(([key, value]) => `${key}: ${value}`)
-  return `---\n${lines.join("\n")}\n---\n`
-}
-
-/**
- * Read a markdown file and parse its content
- */
-function readMarkdownFile(filePath: string): MarkdownFile | null {
-  try {
-    const content = fs.readFileSync(filePath, "utf-8")
-    const { frontmatter, body } = parseFrontmatter(content)
-    const title = frontmatter.title || path.basename(filePath, ".md")
-
-    return {
-      filePath,
-      title,
-      content: body.trim(),
-      hyperspellId: frontmatter.hyperspell_id || null,
-    }
-  } catch (err) {
-    log.error(`Failed to read markdown file: ${filePath}`, err)
-    return null
-  }
-}
-
-/**
- * Update the hyperspell_id in the frontmatter of a markdown file
- */
-function updateFrontmatterId(filePath: string, hyperspellId: string): void {
-  try {
-    const content = fs.readFileSync(filePath, "utf-8")
-    const { frontmatter, body } = parseFrontmatter(content)
-
-    frontmatter.hyperspell_id = hyperspellId
-
-    const newContent = serializeFrontmatter(frontmatter) + body
-    fs.writeFileSync(filePath, newContent)
-
-    log.debug(`Updated frontmatter in ${filePath} with hyperspell_id: ${hyperspellId}`)
-  } catch (err) {
-    log.error(`Failed to update frontmatter in ${filePath}`, err)
-  }
-}
-
-/**
- * Get all markdown files from the memory directory, including subdirectories
- */
-export function getMemoryFiles(workspaceDir: string): string[] {
-  const memoryDir = path.join(workspaceDir, "memory")
-
-  if (!fs.existsSync(memoryDir)) {
-    return []
-  }
-
-  const results: string[] = []
-
-  function walk(dir: string): void {
-    try {
-      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-        const fullPath = path.join(dir, entry.name)
-        if (entry.isDirectory()) {
-          walk(fullPath)
-        } else if (entry.name.endsWith(".md")) {
-          results.push(fullPath)
-        }
-      }
-    } catch (err) {
-      log.error(`Failed to read directory: ${dir}`, err)
-    }
-  }
-
-  walk(memoryDir)
-  return results
-}
-
-/**
- * Sync a single markdown file to Hyperspell
- */
-export async function syncMarkdownFile(
-  client: HyperspellClient,
-  filePath: string,
-  options?: { userId?: string },
-): Promise<{ success: boolean; resourceId?: string; error?: string }> {
-  const file = readMarkdownFile(filePath)
-  if (!file) {
-    return { success: false, error: "Failed to read file" }
-  }
-
-  if (!file.content) {
-    return { success: false, error: "File has no content" }
-  }
-
-  try {
-    const result = await client.addMemory(file.content, {
-      title: file.title,
-      resourceId: file.hyperspellId || undefined,
-      collection: "openclaw",
-      metadata: {
-        openclaw_source: "memory_sync",
-        file_path: filePath,
-      },
-      userId: options?.userId,
-    })
-
-    // Update frontmatter with new resource ID if it changed or was newly created
-    if (result.resourceId !== file.hyperspellId) {
-      updateFrontmatterId(filePath, result.resourceId)
-    }
-
-    return { success: true, resourceId: result.resourceId }
-  } catch (err) {
-    const errorMsg = err instanceof Error ? err.message : String(err)
-    log.error(`Failed to sync ${filePath}`, err)
-    return { success: false, error: errorMsg }
-  }
-}
-
-/**
- * Sync all markdown files in the memory directory
- */
-export async function syncAllMemoryFiles(
-  client: HyperspellClient,
-  workspaceDir: string,
-  options?: { userId?: string },
-): Promise<{ synced: number; failed: number; errors: string[] }> {
-  const files = getMemoryFiles(workspaceDir)
-  let synced = 0
-  let failed = 0
-  const errors: string[] = []
-
-  for (const filePath of files) {
-    const result = await syncMarkdownFile(client, filePath, { userId: options?.userId })
-    if (result.success) {
-      synced++
-      log.info(`Synced: ${path.basename(filePath)} -> ${result.resourceId}`)
-    } else {
-      failed++
-      errors.push(`${path.basename(filePath)}: ${result.error}`)
-    }
-  }
-
-  return { synced, failed, errors }
-}

package/tools/remember.ts

@@ -1,132 +0,0 @@
-import { Type } from "@sinclair/typebox"
-import type { HyperspellClient } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
-import {
-  getDefaultWriteScope,
-  resolveRole,
-  resolveUser,
-  routeWrite,
-} from "../lib/sender.ts"
-import { log } from "../logger.ts"
-
-export function createRememberToolFactory(
-  client: HyperspellClient,
-  cfg: HyperspellConfig,
-) {
-  const scopingEnabled = !!cfg.multiUser?.scoping
-  const availableScopes = cfg.multiUser?.scoping?.scopes ?? []
-  const scopeDescription = scopingEnabled
-    ? `Privacy scope for this memory. Available: ${availableScopes.join(", ")}. Defaults to the user's role default.`
-    : "Privacy scope (only used when scoping is enabled in config)."
-
-  return (ctx: Record<string, unknown>) => ({
-    name: "hyperspell_remember",
-    label: "Memory Store",
-    description: "Save important information to the user's memory.",
-    parameters: Type.Object({
-      text: Type.String({ description: "Information to remember" }),
-      title: Type.Optional(
-        Type.String({ description: "Optional title for the memory" }),
-      ),
-      date: Type.Optional(
-        Type.String({ description: "Date of the memory (ISO 8601 or YYYY-MM-DD). Helps ranking and enables date-range filtering. Defaults to now if omitted." }),
-      ),
-      userId: Type.Optional(
-        Type.String({
-          description:
-            "Store for a specific user or 'shared' for everyone. Omit to store for current sender.",
-        }),
-      ),
-      scope: Type.Optional(
-        Type.String({ description: scopeDescription }),
-      ),
-    }),
-    async execute(
-      _toolCallId: string,
-      params: { text: string; title?: string; date?: string; userId?: string; scope?: string },
-    ) {
-      const resolved = resolveUser(ctx, cfg)
-
-      // Scope resolution: explicit param > role default > global default > "private"
-      const scope =
-        params.scope ??
-        (scopingEnabled ? getDefaultWriteScope(resolved, cfg) : "private")
-
-      // Validate scope is in declared vocabulary (if scoping is enabled)
-      if (
-        scopingEnabled &&
-        availableScopes.length > 0 &&
-        !availableScopes.includes(scope)
-      ) {
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Unknown scope "${scope}". Available: ${availableScopes.join(", ")}.`,
-            },
-          ],
-        }
-      }
-
-      // canWriteScopes enforcement (role-level deny list)
-      if (scopingEnabled) {
-        const role = resolveRole(resolved, cfg)
-        if (role?.canWriteScopes && !role.canWriteScopes.includes(scope)) {
-          return {
-            content: [
-              {
-                type: "text" as const,
-                text: `You cannot write to scope "${scope}".`,
-              },
-            ],
-          }
-        }
-      }
-
-      // Route: explicit userId override takes precedence; otherwise derive from scope
-      let userId: string | undefined
-      let collection: string | undefined
-      if (params.userId) {
-        userId = params.userId
-      } else if (scopingEnabled) {
-        const routed = routeWrite(resolved, scope, cfg)
-        userId = routed.userId
-        collection = routed.collection
-      } else {
-        userId = resolved?.userId
-      }
-
-      log.debug(
-        `remember tool: "${params.text.slice(0, 50)}..." date=${params.date ?? "now"} userId=${userId} scope=${scope}`,
-      )
-
-      try {
-        await client.addMemory(params.text, {
-          title: params.title,
-          date: params.date,
-          collection,
-          metadata: { source: "openclaw_tool" },
-          userId,
-          scope: scopingEnabled ? scope : undefined,
-        })
-
-        const preview =
-          params.text.length > 80 ? `${params.text.slice(0, 80)}…` : params.text
-
-        return {
-          content: [{ type: "text" as const, text: `Stored: "${preview}"` }],
-        }
-      } catch (err) {
-        log.error("remember tool failed", err)
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: `Failed to store memory: ${err instanceof Error ? err.message : String(err)}`,
-            },
-          ],
-        }
-      }
-    },
-  })
-}