loom-claw 0.1.0

package/src/engine.ts

@@ -0,0 +1,387 @@
+/**
+ * LoomContextEngine — OpenClaw Context Engine backed by the Loom Python backend.
+ *
+ * This is a thin integration layer. All cognitive memory logic (schema management,
+ * CM agent, SCP protocol, LLM calls) runs in the Loom FastAPI server.
+ * This engine just calls the right API endpoints at the right lifecycle hooks.
+ *
+ * Lifecycle mapping:
+ *   bootstrap  → verify Loom backend is reachable, ensure session exists
+ *   ingest     → detect /schema <name> command to switch active schema
+ *   assemble   → POST /api/schemas/recall (selective) → fallback GET /api/schemas/recall-all → inject as systemPromptAddition
+ *   afterTurn  → POST /api/build → extract info from new messages into schemas
+ *   compact    → delegate to runtime (schema memory persists independently)
+ *   dispose    → no-op (Loom backend handles persistence)
+ */
+
+import type {
+  ContextEngine,
+  ContextEngineInfo,
+  ContextEngineRuntimeContext,
+} from "openclaw/plugin-sdk";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyMessage = any;
+
+import { LoomClient } from "./client.js";
+import type { LoomPluginConfig } from "./types.js";
+
+interface Logger {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+}
+
+const SCHEMA_CONTEXT_HEADER =
+  "## Loom Persistent Memory (Schema Data)\n" +
+  "The following information has been accumulated about the user across conversations.\n" +
+  "Use it to provide personalized, context-aware responses.\n\n";
+
+export class LoomContextEngine implements ContextEngine {
+  readonly info: ContextEngineInfo = {
+    id: "loom-claw",
+    name: "Loom Cognitive Memory Engine",
+    version: "0.1.0",
+    ownsCompaction: false,
+  };
+
+  private config: LoomPluginConfig;
+  private client: LoomClient;
+  private log: Logger;
+  private turnCounts: Map<string, number> = new Map();
+  private pendingBuildText: Map<string, string[]> = new Map();
+  private sessionIdMap: Map<string, string> = new Map();
+  private activeSchemaId: Map<string, string> = new Map();
+  private backendReachable = false;
+  private cachedSchemaText: string | null = null;
+  private currentOpenclawSessionId: string | null = null;
+  private currentLoomSessionId: string | null = null;
+
+  constructor(config: LoomPluginConfig, logger?: Logger) {
+    this.config = config;
+    this.client = new LoomClient(config.loomBaseUrl);
+    this.log = logger || {
+      info: (...args: unknown[]) => console.log("[loom]", ...args),
+      warn: (...args: unknown[]) => console.warn("[loom]", ...args),
+      error: (...args: unknown[]) => console.error("[loom]", ...args),
+    };
+  }
+
+  private getSchemaId(openclawSessionId: string): string {
+    return this.activeSchemaId.get(openclawSessionId) || this.config.schemaId;
+  }
+
+  private generateSessionId(): string {
+    const now = new Date();
+    const p = (n: number) => String(n).padStart(2, "0");
+    const ts =
+      `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}_` +
+      `${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+    return `session_${ts}`;
+  }
+
+  async bootstrap(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+  }) {
+    this.backendReachable = await this.client.ping();
+    if (!this.backendReachable) {
+      this.log.warn(
+        `Loom backend not reachable at ${this.config.loomBaseUrl}. ` +
+          "Schema memory will not be available until the backend is started.",
+      );
+      return { bootstrapped: false, reason: "backend_unreachable" };
+    }
+
+    this.log.info(`Connected to Loom backend at ${this.config.loomBaseUrl}`);
+
+    if (!this.sessionIdMap.has(params.sessionId)) {
+      this.sessionIdMap.set(params.sessionId, this.generateSessionId());
+    }
+    const loomSessionId = this.sessionIdMap.get(params.sessionId)!;
+    this.currentOpenclawSessionId = params.sessionId;
+    this.currentLoomSessionId = loomSessionId;
+    try {
+      await this.client.createSession(loomSessionId, this.config.schemaId, params.sessionId);
+    } catch {
+      // 409 = session already exists, which is fine
+    }
+
+    const schemaId = this.getSchemaId(params.sessionId);
+    try {
+      const result = await this.client.recallAll(schemaId);
+      this.cachedSchemaText = result.text;
+    } catch {
+      this.cachedSchemaText = null;
+    }
+
+    return { bootstrapped: true };
+  }
+
+  async ingest(params: {
+    sessionId: string;
+    sessionKey?: string;
+    message: AnyMessage;
+    isHeartbeat?: boolean;
+  }) {
+    if (params.isHeartbeat || !this.backendReachable) return { ingested: false };
+
+    const msg = params.message as Record<string, unknown>;
+    const text = extractTextContent(msg.content).trim();
+    const match = text.match(/^\/schema\s+(\S+)/);
+    if (match) {
+      const targetSchemaId = match[1];
+      try {
+        await this.handleSchemaSwitch(targetSchemaId);
+      } catch (e) {
+        this.log.error(`Failed to switch schema to '${targetSchemaId}': ${e}`);
+      }
+    }
+
+    return { ingested: false };
+  }
+
+  async assemble(params: {
+    sessionId: string;
+    sessionKey?: string;
+    messages: AnyMessage[];
+    tokenBudget?: number;
+    model?: string;
+    prompt?: string;
+  }) {
+    let schemaText = this.cachedSchemaText || "";
+    const schemaId = this.getSchemaId(params.sessionId);
+    const loomSessionId = this.sessionIdMap.get(params.sessionId) || params.sessionId;
+
+    if (this.backendReachable) {
+      const userMessage = this._extractLatestUserMessage(params.messages);
+
+      if (userMessage) {
+        try {
+          const result = await this.client.recall(userMessage, loomSessionId, schemaId);
+          schemaText = result.recalled;
+          this.cachedSchemaText = schemaText;
+          if (result.is_selective) {
+            this.log.info("Selective recall succeeded");
+          } else {
+            this.log.info("Selective recall empty, fell back to full schema");
+          }
+        } catch (e) {
+          this.log.warn(`Selective recall failed, falling back to recall-all: ${e}`);
+          try {
+            const fallback = await this.client.recallAll(schemaId);
+            schemaText = fallback.text;
+            this.cachedSchemaText = schemaText;
+          } catch (e2) {
+            this.log.warn(`recall-all also failed, using cache: ${e2}`);
+          }
+        }
+      } else {
+        try {
+          const result = await this.client.recallAll(schemaId);
+          schemaText = result.text;
+          this.cachedSchemaText = schemaText;
+        } catch (e) {
+          this.log.warn(`Failed to recall schemas, using cache: ${e}`);
+        }
+      }
+    }
+
+    const systemPromptAddition = schemaText.trim()
+      ? SCHEMA_CONTEXT_HEADER + schemaText + "\n\n---"
+      : undefined;
+
+    return {
+      messages: params.messages,
+      estimatedTokens: 0,
+      systemPromptAddition,
+    };
+  }
+
+  async afterTurn(params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    messages: AnyMessage[];
+    prePromptMessageCount: number;
+    autoCompactionSummary?: string;
+    isHeartbeat?: boolean;
+    tokenBudget?: number;
+    runtimeContext?: ContextEngineRuntimeContext;
+  }): Promise<void> {
+    if (params.isHeartbeat || !this.backendReachable) return;
+
+    const turnKey = params.sessionId;
+    const count = (this.turnCounts.get(turnKey) || 0) + 1;
+    this.turnCounts.set(turnKey, count);
+
+    const allConversationMessages = params.messages.slice(params.prePromptMessageCount);
+
+    // Find the last user message and take everything from it to the end.
+    // A single turn may contain: [user] -> [assistant tool_call] -> [tool result] -> [assistant reply]
+    // Using slice(-2) would miss the user message when tools are involved.
+    let lastUserIdx = -1;
+    for (let i = allConversationMessages.length - 1; i >= 0; i--) {
+      if ((allConversationMessages[i] as Record<string, unknown>)?.role === "user") {
+        lastUserIdx = i;
+        break;
+      }
+    }
+    const turnMessages = lastUserIdx >= 0
+      ? allConversationMessages.slice(lastUserIdx)
+      : allConversationMessages.slice(-2);
+    const turnText = formatMessagesForBuild(turnMessages);
+
+    this.log.info(
+      `[afterTurn] turn ${count}/${this.config.buildEveryNTurns}, ` +
+      `totalMsgs=${params.messages.length}, prePrompt=${params.prePromptMessageCount}, ` +
+      `convMsgs=${allConversationMessages.length}, lastUserIdx=${lastUserIdx}, ` +
+      `turnMsgs=${turnMessages.length}, ` +
+      `textLen=${turnText.length}, preview=${JSON.stringify(turnText.slice(0, 200))}`,
+    );
+
+    if (turnText.trim()) {
+      const pending = this.pendingBuildText.get(turnKey) || [];
+      pending.push(turnText);
+      this.pendingBuildText.set(turnKey, pending);
+    } else {
+      this.log.warn(`[afterTurn] turn ${count}: turnText is EMPTY, skipping accumulation`);
+    }
+
+    if (count % this.config.buildEveryNTurns !== 0) return;
+
+    const accumulated = this.pendingBuildText.get(turnKey) || [];
+    if (accumulated.length === 0) {
+      this.log.warn(`[afterTurn] turn ${count}: no accumulated text to build`);
+      return;
+    }
+
+    const text = accumulated.join("\n");
+
+    const loomSessionId = this.sessionIdMap.get(turnKey) || turnKey;
+    const sourceId = this.currentOpenclawSessionId || "";
+    this.log.info(`[afterTurn] BUILD sending ${text.length} chars to session=${loomSessionId}`);
+    try {
+      const result = await this.client.build(text, loomSessionId, sourceId);
+      this.log.info(
+        `Schema build completed (session=${loomSessionId}, turn ${count}, ` +
+        `${accumulated.length} segments, result=${JSON.stringify(result)})`,
+      );
+      this.pendingBuildText.set(turnKey, []);
+    } catch (e) {
+      this.log.error(`Schema build failed: ${e}`);
+    }
+  }
+
+  async compact(_params: {
+    sessionId: string;
+    sessionKey?: string;
+    sessionFile: string;
+    tokenBudget?: number;
+    force?: boolean;
+    currentTokenCount?: number;
+    compactionTarget?: "budget" | "threshold";
+    customInstructions?: string;
+    runtimeContext?: ContextEngineRuntimeContext;
+  }) {
+    return {
+      ok: true,
+      compacted: false,
+      reason: "loom-claw delegates compaction to the runtime; schema data persists independently",
+    };
+  }
+
+  async dispose(): Promise<void> {
+    this.cachedSchemaText = null;
+  }
+
+  private _extractLatestUserMessage(messages: AnyMessage[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i] as Record<string, unknown>;
+      if (msg.role === "user") {
+        return extractTextContent(msg.content);
+      }
+    }
+    return "";
+  }
+
+  getClient(): LoomClient {
+    return this.client;
+  }
+
+  getConfig(): LoomPluginConfig {
+    return this.config;
+  }
+
+  updateConfig(patch: Partial<LoomPluginConfig>): void {
+    this.config = { ...this.config, ...patch };
+  }
+
+  getLoomSessionId(): string {
+    return this.currentLoomSessionId || this.config.sessionId;
+  }
+
+  async handleSchemaSwitch(targetSchemaId: string): Promise<{ status: string; message?: string }> {
+    const loomSessionId = this.getLoomSessionId();
+    const sourceId = this.currentOpenclawSessionId || "";
+    let result: { status: string; message?: string };
+    try {
+      result = await this.client.switchSchema(loomSessionId, targetSchemaId, sourceId);
+    } catch (e) {
+      this.log.warn(`Backend switch failed, updating local state anyway: ${e}`);
+      result = { status: "ok", message: "local-only switch (backend call failed)" };
+    }
+    this.onSchemaChanged(targetSchemaId);
+    this.log.info(`Switched session ${loomSessionId} to schema '${targetSchemaId}'`);
+    return result;
+  }
+
+  onSchemaChanged(targetSchemaId: string): void {
+    this.config = { ...this.config, schemaId: targetSchemaId };
+    if (this.currentOpenclawSessionId) {
+      this.activeSchemaId.set(this.currentOpenclawSessionId, targetSchemaId);
+    }
+    this.cachedSchemaText = null;
+  }
+
+  isReachable(): boolean {
+    return this.backendReachable;
+  }
+
+  setReachable(reachable: boolean): void {
+    this.backendReachable = reachable;
+  }
+}
+
+function formatMessagesForBuild(messages: AnyMessage[]): string {
+  const lines: string[] = [];
+  for (const msg of messages) {
+    const m = msg as Record<string, unknown>;
+    const role = m.role || "unknown";
+    const content = extractTextContent(m.content);
+    if (content.trim()) {
+      lines.push(`[${role}]: ${content}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function extractTextContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part: unknown) => {
+        if (typeof part === "string") return part;
+        if (typeof part === "object" && part !== null) {
+          const p = part as Record<string, unknown>;
+          if (p.type === "text" && typeof p.text === "string") return p.text;
+        }
+        return "";
+      })
+      .filter(Boolean)
+      .join("\n");
+  }
+  return "";
+}

package/src/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Type definitions for the Loom OpenClaw plugin.
+ */
+
+export interface LoomPluginConfig {
+  enabled: boolean;
+  loomBaseUrl: string;
+  sessionId: string;
+  schemaId: string;
+  schemaTemplate: string;
+  buildEveryNTurns: number;
+}
+
+export interface BuildResponse {
+  status: string;
+  session_id: string;
+  message: string;
+}
+
+export interface RecallAllResponse {
+  schema_id: string;
+  text: string;
+}
+
+export interface RecallResponse {
+  recalled: string;
+  is_selective: boolean;
+  schema_id: string;
+}
+
+export interface InspectAllResponse {
+  schema_id: string;
+  text: string;
+}
+
+export interface SchemaInfo {
+  name: string;
+  field_count: number;
+  fields: Record<string, string>;
+}
+
+export interface SchemaFileDataResponse {
+  schema_id: string;
+  domains: Array<{
+    name: string;
+    field_count: number;
+    fields: Record<string, string>;
+  }>;
+}
+
+export interface SessionInfo {
+  session_id: string;
+  schema_id: string;
+  file_size: number;
+  chat_rounds: number;
+  schema_count: number;
+}