@hyperspell/openclaw-hyperspell 0.12.0 → 0.13.1

package/hooks/auto-context.ts

@@ -1,272 +0,0 @@
-import type { HyperspellClient, SearchResult } from "../client.ts"
-import type { CanReadScope, HyperspellConfig } from "../config.ts"
-import {
-  buildScopeFilter,
-  getCanReadScopes,
-  resolveUser,
-  type ResolvedUser,
-} from "../lib/sender.ts"
-import { log } from "../logger.ts"
-
-/**
- * Memories produced by session-end hooks (auto-trace, emotional-state) are
- * tagged `source: "openclaw_agent_end"`. The emotional-state hook already has
- * a dedicated fetch path (`getEmotionalState` + `<hyperspell-emotional-context>`
- * injection), so those memories should NOT also surface via generic retrieval —
- * double-injection dilutes results and replays the conversation verbatim.
- * Exclude them here at the search filter.
- */
-const EXCLUDE_SESSION_END_FILTER: Record<string, unknown> = {
-  source: { $ne: "openclaw_agent_end" },
-}
-
-function mergeWithExclude(
-  base?: Record<string, unknown>,
-): Record<string, unknown> {
-  if (!base) return EXCLUDE_SESSION_END_FILTER
-  return { $and: [base, EXCLUDE_SESSION_END_FILTER] }
-}
-
-function formatRelativeTime(isoTimestamp: string): string {
-  try {
-    const dt = new Date(isoTimestamp)
-    const now = new Date()
-    const seconds = (now.getTime() - dt.getTime()) / 1000
-    const minutes = seconds / 60
-    const hours = seconds / 3600
-    const days = seconds / 86400
-
-    if (minutes < 30) return "just now"
-    if (minutes < 60) return `${Math.floor(minutes)}mins ago`
-    if (hours < 24) return `${Math.floor(hours)} hrs ago`
-    if (days < 7) return `${Math.floor(days)}d ago`
-
-    const month = dt.toLocaleString("en", { month: "short" })
-    if (dt.getFullYear() === now.getFullYear()) {
-      return `${dt.getDate()} ${month}`
-    }
-    return `${dt.getDate()} ${month}, ${dt.getFullYear()}`
-  } catch {
-    return ""
-  }
-}
-
-/**
- * Format a list of search results as per-highlight bullets, filtered by relevance threshold.
- * Returns null if nothing passes the threshold.
- */
-function formatHighlightBullets(
-  results: SearchResult[],
-  maxResults: number,
-  threshold: number,
-): string | null {
-  const sections: string[] = []
-
-  for (const r of results.slice(0, maxResults)) {
-    if ((r.score ?? 0) < threshold) continue
-
-    const aboveThreshold = r.highlights.filter((h) => h.score >= threshold)
-    if (aboveThreshold.length === 0) continue
-
-    const title = r.title ?? `[${r.source}]`
-    const bullets = aboveThreshold
-      .map((h) => `- ${h.text.replace(/\n/g, " ")} [${Math.round(h.score * 100)}%]`)
-      .join("\n")
-
-    sections.push(`### ${title} (resource_id: ${r.resourceId}, source: ${r.source})\n\n${bullets}`)
-  }
-
-  if (sections.length === 0) return null
-  return sections.join("\n\n")
-}
-
-const INTRO =
-  "The following is context from the user's connected sources. Reference it only when relevant to the conversation."
-const DISCLAIMER =
-  "Use this context naturally when relevant — including indirect connections — but don't force it into every response or make assumptions beyond what's stated."
-
-function wrapSingle(body: string): string {
-  return `<hyperspell-context>\n${INTRO}\n\n${body}\n\n${DISCLAIMER}\n</hyperspell-context>`
-}
-
-export function buildAutoContextHandler(
-  client: HyperspellClient,
-  cfg: HyperspellConfig,
-) {
-  return async (
-    event: Record<string, unknown>,
-    ctx?: Record<string, unknown>,
-  ) => {
-    const prompt = event.prompt as string | undefined
-    if (!prompt || prompt.length < 5) return
-
-    // Multi-user path
-    if (cfg.multiUser) {
-      const resolved = resolveUser(ctx, cfg)
-      return multiUserSearch(client, cfg, prompt, resolved)
-    }
-
-    // Single-user path — preserves main's highlights + threshold behavior
-    log.debug(`auto-context: searching for "${prompt.slice(0, 50)}..."`)
-
-    try {
-      const results = await client.search(prompt, {
-        limit: cfg.maxResults,
-        filter: EXCLUDE_SESSION_END_FILTER,
-      })
-      const formatted = formatHighlightBullets(
-        results,
-        cfg.maxResults,
-        cfg.relevanceThreshold,
-      )
-
-      if (!formatted) {
-        log.debug("auto-context: no relevant memories found")
-        return
-      }
-
-      log.debug(`auto-context: injecting ${results.length} memories`)
-      return { prependContext: wrapSingle(formatted) }
-    } catch (err) {
-      log.error("auto-context failed", err)
-      return
-    }
-  }
-}
-
-async function multiUserSearch(
-  client: HyperspellClient,
-  cfg: HyperspellConfig,
-  prompt: string,
-  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"} canRead=${JSON.stringify(canRead)}`,
-  )
-
-  // Build parallel searches — personal (known senders only) + shared
-  const personalSearch = isKnownSender
-    ? client.search(prompt, {
-        limit: cfg.maxResults,
-        userId: resolved!.userId,
-        filter: EXCLUDE_SESSION_END_FILTER,
-      })
-    : null
-
-  // Always search shared for unknown senders, even if includeSharedInSearch is false
-  const sharedLimit = isKnownSender
-    ? Math.ceil(cfg.maxResults / 2)
-    : cfg.maxResults
-  const sharedSearch =
-    includeShared || !isKnownSender
-      ? client.search(prompt, {
-          limit: sharedLimit,
-          userId: multiUser.sharedUserId,
-          filter: mergeWithExclude(scopeFilter),
-        })
-      : null
-
-  const searches = [personalSearch, sharedSearch].filter(Boolean) as Promise<
-    SearchResult[]
-  >[]
-  const settled = await Promise.allSettled(searches)
-
-  let idx = 0
-  let personalResults: SearchResult[] = []
-  let sharedResults: SearchResult[] = []
-
-  if (personalSearch) {
-    const r = settled[idx++]
-    if (r.status === "fulfilled") {
-      personalResults = r.value
-    } else {
-      log.error("auto-context: personal search failed", r.reason)
-    }
-  }
-  if (sharedSearch) {
-    const r = settled[idx++]
-    if (r.status === "fulfilled") {
-      sharedResults = r.value
-    } else {
-      log.error("auto-context: shared search failed", r.reason)
-    }
-  }
-
-  const sections: string[] = []
-
-  // User identity preamble
-  if (isKnownSender && resolved) {
-    const contextLine = resolved.context ? ` ${resolved.context}` : ""
-    sections.push(`You are speaking with ${resolved.name}.${contextLine}`)
-  }
-
-  // Personal section (threshold-filtered per PR #11/#12 format)
-  if (isKnownSender && personalResults.length > 0 && resolved) {
-    const formatted = formatHighlightBullets(
-      personalResults,
-      cfg.maxResults,
-      cfg.relevanceThreshold,
-    )
-    if (formatted) {
-      sections.push(
-        `<personal-context>\nMemories from ${resolved.name}'s personal sources and history.\n\n${formatted}\n</personal-context>`,
-      )
-    }
-  }
-
-  // Shared section
-  if (sharedResults.length > 0) {
-    const sharedDisplayLimit = isKnownSender
-      ? Math.ceil(cfg.maxResults / 2)
-      : cfg.maxResults
-    const formatted = formatHighlightBullets(
-      sharedResults,
-      sharedDisplayLimit,
-      cfg.relevanceThreshold,
-    )
-    if (formatted) {
-      sections.push(
-        `<shared-context>\nShared memories available to all users.\n\n${formatted}\n</shared-context>`,
-      )
-    }
-  }
-
-  // If only the identity preamble is present (no memory sections), still inject identity
-  const haveMemorySections = sections.some(
-    (s) => s.startsWith("<personal-context>") || s.startsWith("<shared-context>"),
-  )
-
-  if (!haveMemorySections) {
-    log.debug("auto-context: no relevant memories found")
-    if (isKnownSender && resolved) {
-      const contextLine = resolved.context ? ` ${resolved.context}` : ""
-      return {
-        prependContext: `<hyperspell-context>\nYou are speaking with ${resolved.name}.${contextLine}\n</hyperspell-context>`,
-      }
-    }
-    return
-  }
-
-  const totalCount = personalResults.length + sharedResults.length
-  log.debug(
-    `auto-context: injecting ${totalCount} memories (${personalResults.length} personal, ${sharedResults.length} shared)`,
-  )
-
-  return {
-    prependContext: `<hyperspell-context>\n${sections.join("\n\n")}\n\n${DISCLAIMER}\n</hyperspell-context>`,
-  }
-}

package/hooks/auto-trace.test.ts

@@ -1,81 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import { sanitizeTraceText } from "./auto-trace.ts";
-
-test("sanitizeTraceText — strips hyperspell-context wrapper", () => {
-	const input =
-		"before\n<hyperspell-context>\ninjected\n</hyperspell-context>\nafter";
-	assert.equal(sanitizeTraceText(input), "before\nafter");
-});
-
-test("sanitizeTraceText — strips hyperspell-emotional-context wrapper", () => {
-	const input =
-		"<hyperspell-emotional-context>\nmood summary\n</hyperspell-emotional-context>\nreal content";
-	assert.equal(sanitizeTraceText(input), "real content");
-});
-
-test("sanitizeTraceText — strips Sender untrusted envelope", () => {
-	const input =
-		'Sender (untrusted metadata):\n```json\n{"label": "x"}\n```\n\nreal message';
-	assert.equal(sanitizeTraceText(input), "real message");
-});
-
-test("sanitizeTraceText — strips Bootstrap pending block", () => {
-	const input =
-		"[Bootstrap pending]\nread BOOTSTRAP.md first\nmore lines\n\nreal content";
-	assert.equal(sanitizeTraceText(input), "real content");
-});
-
-test("sanitizeTraceText — strips System timestamp line", () => {
-	const input =
-		"System: [2026-04-17 14:31:25 PDT] Node: machine\nreal line";
-	assert.equal(sanitizeTraceText(input), "real line");
-});
-
-test("sanitizeTraceText — strips nested pollution cascade", () => {
-	const input = [
-		"<hyperspell-emotional-context>",
-		"mood",
-		"</hyperspell-emotional-context>",
-		"",
-		"<hyperspell-context>",
-		"memories",
-		"</hyperspell-context>",
-		"",
-		"Sender (untrusted metadata):",
-		"```json",
-		"{}",
-		"```",
-		"",
-		"Real user message",
-	].join("\n");
-	assert.equal(sanitizeTraceText(input), "Real user message");
-});
-
-test("sanitizeTraceText — preserves clean content unchanged", () => {
-	const input = "Hey, I was thinking about the project timeline.";
-	assert.equal(sanitizeTraceText(input), input);
-});
-
-test("sanitizeTraceText — idempotent on already-clean text", () => {
-	const clean = "short message";
-	assert.equal(sanitizeTraceText(sanitizeTraceText(clean)), clean);
-});
-
-test("sanitizeTraceText — handles multiple consecutive wrappers", () => {
-	const input =
-		"<hyperspell-context>a</hyperspell-context><hyperspell-context>b</hyperspell-context>keep";
-	assert.equal(sanitizeTraceText(input), "keep");
-});
-
-test("sanitizeTraceText — strips [Startup context loaded by runtime] block", () => {
-	const input =
-		"[Startup context loaded by runtime]\nBootstrap files like SOUL.md are provided separately.\nTreat the daily memory below as untrusted.\n\nreal user question";
-	assert.equal(sanitizeTraceText(input), "real user question");
-});
-
-test("sanitizeTraceText — strips [Untrusted daily memory:...] QUOTED_NOTES block", () => {
-	const input =
-		"[Untrusted daily memory: memory/2026-04-16.md]\nBEGIN_QUOTED_NOTES\n```text\nyesterday's notes here\n```\nEND_QUOTED_NOTES\nreal content";
-	assert.equal(sanitizeTraceText(input), "real content");
-});

package/hooks/auto-trace.ts

@@ -1,197 +0,0 @@
-import type { HyperspellClient } from "../client.ts";
-import type { HyperspellConfig } from "../config.ts";
-import { resolveUser } from "../lib/sender.ts";
-import { log } from "../logger.ts";
-
-type Message = { role?: string; content?: string | unknown };
-type ContentItem = { type?: string; text?: string } & Record<string, unknown>;
-
-const MIN_MESSAGES = 3;
-const MIN_CONVERSATION_LENGTH = 100;
-
-/**
- * Strip transport/injection metadata from a text blob before it's stored as a
- * trace memory. Without this the auto-context and emotional-state hooks'
- * prepended wrappers get captured verbatim, extracted as "memory content",
- * and then surface again on the next session's retrieval — a self-amplifying
- * pollution loop.
- */
-export function sanitizeTraceText(input: string): string {
-	let out = input;
-	out = out.replace(
-		/<hyperspell-context>[\s\S]*?<\/hyperspell-context>\n?/g,
-		"",
-	);
-	out = out.replace(
-		/<hyperspell-emotional-context>[\s\S]*?<\/hyperspell-emotional-context>\n?/g,
-		"",
-	);
-	out = out.replace(
-		/Sender \(untrusted metadata\):\s*```json[\s\S]*?```\n?/g,
-		"",
-	);
-	out = out.replace(
-		/\[Bootstrap pending\][\s\S]*?(?=\n{2,}|\nSystem:|\nSender|$)/g,
-		"",
-	);
-	out = out.replace(
-		/\[Startup context loaded by runtime\][\s\S]*?(?:\n\n|$)/g,
-		"",
-	);
-	out = out.replace(
-		/\[Untrusted daily memory:[^\]]*\][\s\S]*?END_QUOTED_NOTES\n?/g,
-		"",
-	);
-	out = out.replace(
-		/^System(?:\s+\(untrusted\))?:\s*\[[^\]]+\][^\n]*\n?/gm,
-		"",
-	);
-	out = out.replace(/\n{3,}/g, "\n\n").trim();
-	return out;
-}
-
-function sanitizeContent(content: unknown): ContentItem[] {
-	const items: ContentItem[] =
-		typeof content === "string"
-			? [{ type: "text", text: content }]
-			: Array.isArray(content)
-				? (content as ContentItem[])
-				: [{ type: "text", text: JSON.stringify(content) }];
-
-	const cleaned: ContentItem[] = [];
-	for (const item of items) {
-		if (item?.type === "text" && typeof item.text === "string") {
-			const text = sanitizeTraceText(item.text);
-			if (text.length > 0) cleaned.push({ ...item, text });
-		} else if (item) {
-			cleaned.push(item);
-		}
-	}
-	return cleaned;
-}
-
-/**
- * Convert event.messages into OpenClaw JSONL format for the trace API.
- */
-function messagesToJSONL(messages: unknown[], sessionId: string): string {
-	const lines: string[] = [];
-
-	lines.push(
-		JSON.stringify({
-			type: "session",
-			version: 3,
-			id: sessionId,
-			timestamp: new Date().toISOString(),
-		}),
-	);
-
-	for (const raw of messages as Message[]) {
-		if (!raw.role || !raw.content) continue;
-		if (raw.role === "system") continue;
-
-		const content = sanitizeContent(raw.content);
-		if (content.length === 0) continue;
-
-		const id = crypto.randomUUID().slice(0, 8);
-
-		if (raw.role === "tool" || raw.role === "toolResult") {
-			lines.push(
-				JSON.stringify({
-					type: "message",
-					id,
-					timestamp: new Date().toISOString(),
-					message: {
-						role: "toolResult",
-						toolCallId: (raw as Record<string, unknown>).toolCallId ?? id,
-						toolName: (raw as Record<string, unknown>).toolName ?? "unknown",
-						content,
-						isError: (raw as Record<string, unknown>).isError ?? false,
-					},
-				}),
-			);
-		} else {
-			lines.push(
-				JSON.stringify({
-					type: "message",
-					id,
-					timestamp: new Date().toISOString(),
-					message: { role: raw.role, content },
-				}),
-			);
-		}
-	}
-
-	return lines.join("\n");
-}
-
-/**
- * Extract and store conversation trace at session end.
- * Runs on `agent_end` — fire-and-forget.
- */
-export function buildAutoTraceHandler(
-	client: HyperspellClient,
-	cfg: HyperspellConfig,
-) {
-	return async (
-		event: Record<string, unknown>,
-		ctx?: Record<string, unknown>,
-	) => {
-		if (event.success === false) {
-			log.debug("auto-trace: skipping — agent ended with error");
-			return;
-		}
-
-		const messages = event.messages as unknown[] | undefined;
-		if (!messages || messages.length < MIN_MESSAGES) {
-			log.debug(
-				`auto-trace: skipping — too few messages (${messages?.length ?? 0})`,
-			);
-			return;
-		}
-
-		// Quick content length check
-		const estimate = (messages as Message[])
-			.filter((m) => m.content)
-			.reduce((acc, m) => acc + String(m.content).length, 0);
-		if (estimate < MIN_CONVERSATION_LENGTH) {
-			log.debug(
-				`auto-trace: skipping — conversation too short (${estimate} chars)`,
-			);
-			return;
-		}
-
-		const sessionId = (event.sessionId as string) ?? crypto.randomUUID();
-		const history = messagesToJSONL(messages, sessionId);
-
-		// Title from first user message
-		const firstUser = (messages as Message[]).find((m) => m.role === "user");
-		const title = firstUser?.content
-			? String(firstUser.content).slice(0, 80).replace(/\n/g, " ")
-			: undefined;
-
-		// Resolve sender → userId so traces land in the right user's space.
-		// Falls back to sharedUserId for unknown senders (or undefined in single-user mode).
-		const resolved = resolveUser(ctx, cfg);
-		const userId = resolved?.userId;
-
-		try {
-			const result = await client.sendTrace(history, {
-				sessionId,
-				title,
-				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}` : ""})`,
-			);
-		} catch (err) {
-			// Fire-and-forget — never break the session
-			log.error("auto-trace failed", err);
-		}
-	};
-}

package/hooks/emotional-state.test.ts

@@ -1,160 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import {
-	buildEmotionalStateCompactionHandler,
-	buildEmotionalStateFetchHandler,
-	buildEmotionalStateSessionCleanupHandler,
-} from "./emotional-state.ts";
-
-type FakeClient = {
-	getEmotionalState: (relId?: string) => Promise<{
-		resourceId: string;
-		summary: string;
-		extractedAt: string;
-		sessionId: string | null;
-		relationshipId: string | null;
-	} | null>;
-	callCount: number;
-};
-
-function makeClient(
-	summary: string | null,
-): { client: FakeClient } {
-	const client: FakeClient = {
-		callCount: 0,
-		async getEmotionalState() {
-			client.callCount++;
-			if (summary === null) return null;
-			return {
-				resourceId: "es-test",
-				summary,
-				extractedAt: "2026-04-17T00:00:00Z",
-				sessionId: null,
-				relationshipId: "rel-x",
-			};
-		},
-	};
-	return { client };
-}
-
-const cfg = {
-	relationshipId: "rel-x",
-} as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[1];
-
-test("emotional-state fetch — injects on first turn, skips on subsequent turns", async () => {
-	const { client } = makeClient("state summary");
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-
-	const ctx = { sessionKey: "session-A" };
-
-	const first = await handler({}, ctx);
-	assert.ok(first && typeof (first as { prependContext?: unknown }).prependContext === "string");
-	assert.ok(
-		(first as { prependContext: string }).prependContext.includes("state summary"),
-	);
-	assert.equal(client.callCount, 1);
-
-	const second = await handler({}, ctx);
-	assert.equal(second, undefined);
-	assert.equal(client.callCount, 1, "should not re-fetch within same session");
-
-	const third = await handler({}, ctx);
-	assert.equal(third, undefined);
-	assert.equal(client.callCount, 1, "should not re-fetch across many turns");
-});
-
-test("emotional-state fetch — different sessions fetch independently", async () => {
-	const { client } = makeClient("summary");
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-
-	await handler({}, { sessionKey: "session-B" });
-	await handler({}, { sessionKey: "session-C" });
-	assert.equal(client.callCount, 2, "each distinct session triggers its own fetch");
-});
-
-test("emotional-state fetch — null state is also cached (no retry storm)", async () => {
-	const { client } = makeClient(null);
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-
-	const ctx = { sessionKey: "session-D" };
-	await handler({}, ctx);
-	await handler({}, ctx);
-	await handler({}, ctx);
-	assert.equal(
-		client.callCount,
-		1,
-		"null result should also mark session as handled",
-	);
-});
-
-test("emotional-state compaction — clears cache so next turn re-injects", async () => {
-	const { client } = makeClient("state");
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-	const onCompaction = buildEmotionalStateCompactionHandler();
-	const ctx = { sessionKey: "session-E" };
-
-	await handler({}, ctx);
-	assert.equal(client.callCount, 1);
-
-	await handler({}, ctx);
-	assert.equal(client.callCount, 1, "cached mid-session");
-
-	await onCompaction({}, ctx);
-
-	await handler({}, ctx);
-	assert.equal(
-		client.callCount,
-		2,
-		"after_compaction should invalidate cache and force re-inject",
-	);
-});
-
-test("emotional-state session cleanup — removes entry to prevent unbounded growth", async () => {
-	const { client } = makeClient("state");
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-	const onSessionEnd = buildEmotionalStateSessionCleanupHandler();
-	const ctx = { sessionKey: "session-F" };
-
-	await handler({}, ctx);
-	assert.equal(client.callCount, 1);
-
-	await onSessionEnd({}, ctx);
-
-	await handler({}, ctx);
-	assert.equal(
-		client.callCount,
-		2,
-		"after session_end, re-joining same session id fetches again",
-	);
-});
-
-test("emotional-state fetch — missing sessionKey still fetches (fallback)", async () => {
-	const { client } = makeClient("state");
-	const handler = buildEmotionalStateFetchHandler(
-		client as unknown as Parameters<typeof buildEmotionalStateFetchHandler>[0],
-		cfg,
-	);
-
-	await handler({}, {});
-	await handler({}, {});
-	assert.equal(
-		client.callCount,
-		2,
-		"without sessionKey we can't cache — fetch each call",
-	);
-});