@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/hooks/emotional-state.ts

@@ -1,179 +0,0 @@
-import type { HyperspellClient } from "../client.ts";
-import type { HyperspellConfig } from "../config.ts";
-import { log } from "../logger.ts";
-import { sanitizeTraceText } from "./auto-trace.ts";
-
-type Message = { role?: string; content?: string | unknown };
-type AgentContext = { sessionKey?: string };
-
-const MIN_MESSAGES = 3;
-const MIN_CONVERSATION_LENGTH = 100;
-
-/**
- * Sessions where emotional context has already been injected this run.
- * Emotional state doesn't change within a session (it's extracted at
- * agent_end and surfaces on the *next* session), so re-fetching and
- * re-injecting on every turn is pure cost — one API call and a few
- * hundred tokens of repeated wrapper per turn.
- *
- * Lifecycle:
- *  - first before_agent_start in a session: fetch, inject, mark.
- *  - subsequent turns in same session: skip (return undefined).
- *  - after_compaction: clear the mark so the next turn re-injects (the
- *    initial injection may have been compacted out of history).
- *  - session_end: clean up to prevent unbounded Set growth.
- */
-const injectedSessions = new Set<string>();
-
-/**
- * Extract readable text from a message content, unwrapping the common
- * `[{ type: "text", text: "..." }]` array shape so sanitizeTraceText can
- * operate on real text (not JSON-stringified content where newlines would
- * be escaped and regex line-anchors wouldn't match).
- */
-function contentToText(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (Array.isArray(content)) {
-		const texts: string[] = [];
-		for (const item of content) {
-			if (
-				item &&
-				typeof item === "object" &&
-				(item as { type?: unknown }).type === "text" &&
-				typeof (item as { text?: unknown }).text === "string"
-			) {
-				texts.push((item as { text: string }).text);
-			}
-		}
-		if (texts.length > 0) return texts.join("\n");
-	}
-	return "";
-}
-
-function messagesToTranscript(messages: unknown[]): string {
-	const lines: string[] = [];
-	for (const m of messages as Message[]) {
-		if (!m.role || !m.content) continue;
-		if (m.role === "system") continue;
-		const raw = contentToText(m.content);
-		if (!raw) continue;
-		const cleaned = sanitizeTraceText(raw);
-		if (cleaned.length === 0) continue;
-		lines.push(`${m.role}: ${cleaned}`);
-	}
-	return lines.join("\n");
-}
-
-/**
- * Fetch emotional state on the first agent turn of a session and inject into
- * context. On later turns of the same session, return undefined — the
- * injection from the first turn is already in the conversation history.
- *
- * Runs on `before_agent_start` (which fires every turn).
- */
-export function buildEmotionalStateFetchHandler(
-	client: HyperspellClient,
-	cfg: HyperspellConfig,
-) {
-	return async (_event: Record<string, unknown>, ctx?: AgentContext) => {
-		const sessionKey = ctx?.sessionKey;
-		if (sessionKey && injectedSessions.has(sessionKey)) {
-			return;
-		}
-
-		try {
-			const state = await client.getEmotionalState(cfg.relationshipId);
-
-			if (!state) {
-				log.debug("emotional-context: no prior emotional state found");
-				if (sessionKey) injectedSessions.add(sessionKey);
-				return;
-			}
-
-			log.debug(`emotional-context: injecting state from ${state.extractedAt}`);
-
-			const context = [
-				"<hyperspell-emotional-context>",
-				"The following captures the emotional register of your relationship with this user from your last interaction. Let it inform your tone — don't reference it explicitly.",
-				"",
-				state.summary,
-				"</hyperspell-emotional-context>",
-			].join("\n");
-
-			if (sessionKey) injectedSessions.add(sessionKey);
-			return { prependContext: context };
-		} catch (err) {
-			log.error("emotional-context fetch failed", err);
-			return;
-		}
-	};
-}
-
-/**
- * After compaction, the emotional-context block from the first turn may have
- * been trimmed out of history. Clear the cache so the next turn re-injects.
- */
-export function buildEmotionalStateCompactionHandler() {
-	return async (_event: Record<string, unknown>, ctx?: AgentContext) => {
-		const sessionKey = ctx?.sessionKey;
-		if (sessionKey && injectedSessions.delete(sessionKey)) {
-			log.debug(
-				`emotional-context: cache cleared after compaction (session=${sessionKey})`,
-			);
-		}
-	};
-}
-
-/**
- * Remove session from the inject-once cache when the session ends, to keep the
- * Set from growing unbounded over process lifetime.
- */
-export function buildEmotionalStateSessionCleanupHandler() {
-	return async (_event: Record<string, unknown>, ctx?: AgentContext) => {
-		const sessionKey = ctx?.sessionKey;
-		if (sessionKey) injectedSessions.delete(sessionKey);
-	};
-}
-
-/**
- * Extract and store emotional state at session end.
- * Runs on `agent_end` — fire-and-forget.
- */
-export function buildEmotionalStateStoreHandler(
-	client: HyperspellClient,
-	cfg: HyperspellConfig,
-) {
-	return async (event: Record<string, unknown>) => {
-		if (event.success === false) {
-			log.debug("emotional-state: skipping — agent ended with error");
-			return;
-		}
-
-		const messages = event.messages as unknown[] | undefined;
-		if (!messages || messages.length < MIN_MESSAGES) {
-			log.debug(
-				`emotional-state: skipping — too few messages (${messages?.length ?? 0})`,
-			);
-			return;
-		}
-
-		const transcript = messagesToTranscript(messages);
-		if (transcript.length < MIN_CONVERSATION_LENGTH) {
-			log.debug(
-				`emotional-state: skipping — conversation too short (${transcript.length} chars)`,
-			);
-			return;
-		}
-
-		try {
-			const result = await client.storeEmotionalState(transcript, {
-				relationshipId: cfg.relationshipId,
-				metadata: { source: "openclaw_agent_end" },
-			});
-			log.info(`emotional-state: stored ${result.resourceId}`);
-		} catch (err) {
-			// Fire-and-forget — never let this break the session
-			log.error("emotional-state store failed", err);
-		}
-	};
-}

package/hooks/memory-sync.ts

@@ -1,65 +0,0 @@
-import * as path from "node:path"
-import type { HyperspellClient } from "../client.ts"
-import type { HyperspellConfig } from "../config.ts"
-import { getWorkspaceDir } from "../config.ts"
-import { log } from "../logger.ts"
-import { syncMarkdownFile, syncAllMemoryFiles } from "../sync/markdown.ts"
-
-/**
- * Build a handler for file change events that syncs markdown files to Hyperspell
- */
-export function buildFileSyncHandler(client: HyperspellClient, cfg: HyperspellConfig) {
-  const workspaceDir = getWorkspaceDir()
-  const memoryDir = path.join(workspaceDir, "memory")
-  const syncUserId = cfg.multiUser?.sharedUserId
-
-  return async (event: Record<string, unknown>) => {
-    const filePath = event.file_path as string | undefined
-    if (!filePath) return
-
-    // Only process markdown files in the workspace's memory directory
-    if (!filePath.startsWith(memoryDir) || !filePath.endsWith(".md")) {
-      return
-    }
-
-    const fileName = path.basename(filePath)
-    log.info(`Memory file changed: ${fileName}`)
-
-    try {
-      const result = await syncMarkdownFile(client, filePath, { userId: syncUserId })
-      if (result.success) {
-        log.info(`Synced ${fileName} -> ${result.resourceId}`)
-      } else {
-        log.error(`Failed to sync ${fileName}: ${result.error}`)
-      }
-    } catch (err) {
-      log.error(`Error syncing ${fileName}`, err)
-    }
-  }
-}
-
-/**
- * Sync all existing memory files on startup
- */
-export async function syncMemoriesOnStartup(
-  client: HyperspellClient,
-  workspaceDir: string,
-  options?: { userId?: string },
-): Promise<void> {
-  log.info("Syncing existing memory files...")
-
-  const result = await syncAllMemoryFiles(client, workspaceDir, { userId: options?.userId })
-
-  if (result.synced > 0) {
-    log.info(`Synced ${result.synced} memory files`)
-  }
-  if (result.failed > 0) {
-    log.error(`Failed to sync ${result.failed} files:`)
-    for (const error of result.errors) {
-      log.error(`  - ${error}`)
-    }
-  }
-  if (result.synced === 0 && result.failed === 0) {
-    log.info("No memory files found in memory/ directory")
-  }
-}

package/index.ts

@@ -1,152 +0,0 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk"
-import { HyperspellClient } from "./client.ts"
-import { registerCommands } from "./commands/slash.ts"
-import { registerCliCommands } from "./commands/setup.ts"
-import { parseConfig, hyperspellConfigSchema, getWorkspaceDir } from "./config.ts"
-import { buildAutoContextHandler } from "./hooks/auto-context.ts"
-import { buildAutoTraceHandler } from "./hooks/auto-trace.ts"
-import {
-	buildEmotionalStateCompactionHandler,
-	buildEmotionalStateFetchHandler,
-	buildEmotionalStateSessionCleanupHandler,
-	buildEmotionalStateStoreHandler,
-} from "./hooks/emotional-state.ts"
-import { buildFileSyncHandler, syncMemoriesOnStartup } from "./hooks/memory-sync.ts"
-import { initLogger } from "./logger.ts"
-import { createRememberToolFactory } from "./tools/remember.ts"
-import { createSearchToolFactory } from "./tools/search.ts"
-import { registerNetworkTools } from "./graph/index.ts"
-
-export default {
-	id: "openclaw-hyperspell",
-	name: "Hyperspell",
-	description:
-		"Hyperspell gives your Molty context and memory from all your existing data",
-	kind: "memory" as const,
-	configSchema: hyperspellConfigSchema,
-
-	register(api: OpenClawPluginApi) {
-		// Register CLI commands (openclaw openclaw-hyperspell setup|status|connect)
-		api.registerCli(
-			(ctx) => {
-				registerCliCommands(ctx.program, api.pluginConfig);
-			},
-			{ commands: ["openclaw-hyperspell"] },
-		);
-
-		// Check if configured
-		const rawConfig = api.pluginConfig as Record<string, unknown> | undefined;
-		const hasConfig = rawConfig?.apiKey || process.env.HYPERSPELL_API_KEY;
-
-		if (!hasConfig) {
-			api.logger.info(
-				"hyperspell: not configured - run 'openclaw openclaw-hyperspell setup'",
-			)
-			// Still register slash commands so they show up, but they'll return an error
-			api.registerCommand({
-				name: "getcontext",
-				description: "Search your memories for relevant context",
-				acceptsArgs: true,
-				requireAuth: false,
-				handler: async () => {
-					return {
-						text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
-					}
-				},
-			})
-			api.registerCommand({
-				name: "remember",
-				description: "Save something to memory",
-				acceptsArgs: true,
-				requireAuth: false,
-				handler: async () => {
-					return {
-						text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
-					}
-				},
-			})
-			api.registerCommand({
-				name: "sync",
-				description: "Sync memory/*.md files with Hyperspell",
-				acceptsArgs: false,
-				requireAuth: false,
-				handler: async () => {
-					return {
-						text: "Hyperspell not configured. Run 'openclaw openclaw-hyperspell setup' first.",
-					}
-				},
-			})
-			return
-		}
-
-		const cfg = parseConfig(api.pluginConfig);
-
-		initLogger(api.logger, cfg.debug);
-
-		const client = new HyperspellClient(cfg);
-
-		// Register AI tools (factory pattern for sender context)
-		api.registerTool(createSearchToolFactory(client, cfg), {
-			name: "hyperspell_search",
-		});
-		api.registerTool(createRememberToolFactory(client, cfg), {
-			name: "hyperspell_remember",
-		});
-
-		// Register emotional context hooks.
-		// - fetch: inject once per session on first turn (cached thereafter)
-		// - compaction: clear cache so the next turn re-injects after trim
-		// - session cleanup: drop Set entry on session end
-		// - store: extract new emotional state from the finished session
-		if (cfg.emotionalContext) {
-			api.on("before_agent_start", buildEmotionalStateFetchHandler(client, cfg));
-			api.on("after_compaction", buildEmotionalStateCompactionHandler());
-			api.on("session_end", buildEmotionalStateSessionCleanupHandler());
-			api.on("agent_end", buildEmotionalStateStoreHandler(client, cfg));
-		}
-
-		// Register auto-context hook
-		if (cfg.autoContext) {
-			const autoContextHandler = buildAutoContextHandler(client, cfg);
-			api.on("before_agent_start", autoContextHandler);
-		}
-
-		// Register auto-trace hook (send conversations to Hyperspell on session end)
-		if (cfg.autoTrace.enabled) {
-			api.on("agent_end", buildAutoTraceHandler(client, cfg));
-		}
-
-		// Register memory sync hook
-		if (cfg.syncMemories) {
-			const fileSyncHandler = buildFileSyncHandler(client, cfg);
-			api.on("file_changed", fileSyncHandler);
-		}
-
-		// Register memory network tools
-		if (cfg.knowledgeGraph.enabled) {
-			registerNetworkTools(api, client, cfg);
-		}
-
-		// Register slash commands
-		registerCommands(api, client, cfg);
-
-		// Register service for lifecycle management
-		api.registerService({
-			id: "openclaw-hyperspell",
-			start: async () => {
-				api.logger.info("hyperspell: connected");
-
-				// Sync memories on startup if enabled
-				if (cfg.syncMemories) {
-					const workspaceDir = getWorkspaceDir();
-					await syncMemoriesOnStartup(client, workspaceDir, {
-						userId: cfg.multiUser?.sharedUserId,
-					});
-				}
-			},
-			stop: () => {
-				api.logger.info("hyperspell: stopped");
-			},
-		});
-	},
-};

package/lib/browser.ts

@@ -1,31 +0,0 @@
-import { execFile } from "node:child_process"
-import { platform } from "node:os"
-
-export function openInBrowser(url: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    let file: string
-    let args: string[]
-
-    switch (platform()) {
-      case "darwin":
-        file = "open"
-        args = [url]
-        break
-      case "win32":
-        file = "cmd"
-        args = ["/c", "start", "", url]
-        break
-      default:
-        file = "xdg-open"
-        args = [url]
-    }
-
-    execFile(file, args, (error) => {
-      if (error) {
-        reject(error)
-      } else {
-        resolve()
-      }
-    })
-  })
-}

package/lib/sender.test.ts

@@ -1,234 +0,0 @@
-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" })
-})