@parkgogogo/openclaw-reflection 0.1.0

package/src/proper-lockfile.d.ts

@@ -0,0 +1,25 @@
+declare module "proper-lockfile" {
+  export interface RetryOptions {
+    retries?: number;
+    factor?: number;
+    minTimeout?: number;
+    maxTimeout?: number;
+    randomize?: boolean;
+  }
+
+  export interface LockOptions {
+    retries?: number | RetryOptions;
+    stale?: number;
+    realpath?: boolean;
+  }
+
+  export type Release = () => Promise<void>;
+
+  export function lock(filePath: string, options?: LockOptions): Promise<Release>;
+
+  const lockfile: {
+    lock: typeof lock;
+  };
+
+  export default lockfile;
+}

package/src/session-manager.ts

@@ -0,0 +1,114 @@
+import { CircularBuffer } from "./buffer.js";
+import type { Logger, ReflectionMessage } from "./types.js";
+
+interface SessionData {
+  buffer: CircularBuffer<ReflectionMessage>;
+  lastAccessed: number;
+  processedAgentMessageIds: Set<string>;
+  pendingTask: Promise<void>;
+}
+
+export class SessionBufferManager {
+  private sessions: Map<string, SessionData>;
+  private capacity: number;
+  private logger: Logger;
+
+  constructor(capacity: number, logger: Logger) {
+    this.capacity = capacity;
+    this.logger = logger;
+    this.sessions = new Map();
+  }
+
+  private getOrCreateSessionData(sessionKey: string): SessionData {
+    let sessionData = this.sessions.get(sessionKey);
+
+    if (!sessionData) {
+      this.logger.info(
+        "SessionBufferManager",
+        "Creating new session buffer",
+        { sessionKey },
+        sessionKey
+      );
+      sessionData = {
+        buffer: new CircularBuffer<ReflectionMessage>(this.capacity),
+        lastAccessed: Date.now(),
+        processedAgentMessageIds: new Set<string>(),
+        pendingTask: Promise.resolve(),
+      };
+      this.sessions.set(sessionKey, sessionData);
+    }
+
+    sessionData.lastAccessed = Date.now();
+    return sessionData;
+  }
+
+  push(sessionKey: string, message: ReflectionMessage): void {
+    const sessionData = this.getOrCreateSessionData(sessionKey);
+
+    const evicted = sessionData.buffer.push(message);
+    if (evicted) {
+      this.logger.info(
+        "SessionBufferManager",
+        "Evicted oldest message",
+        { evictedId: evicted.id },
+        sessionKey
+      );
+    }
+
+    sessionData.lastAccessed = Date.now();
+  }
+
+  getMessages(sessionKey: string): ReflectionMessage[] {
+    const sessionData = this.sessions.get(sessionKey);
+
+    if (!sessionData) {
+      return [];
+    }
+
+    sessionData.lastAccessed = Date.now();
+    return sessionData.buffer.toArray();
+  }
+
+  hasProcessedAgentMessage(sessionKey: string, messageId: string): boolean {
+    const sessionData = this.sessions.get(sessionKey);
+    if (!sessionData) {
+      return false;
+    }
+
+    sessionData.lastAccessed = Date.now();
+    return sessionData.processedAgentMessageIds.has(messageId);
+  }
+
+  markProcessedAgentMessage(sessionKey: string, messageId: string): void {
+    const sessionData = this.getOrCreateSessionData(sessionKey);
+    sessionData.processedAgentMessageIds.add(messageId);
+  }
+
+  runExclusive(sessionKey: string, task: () => Promise<void>): Promise<void> {
+    const sessionData = this.getOrCreateSessionData(sessionKey);
+    const nextTask = sessionData.pendingTask
+      .catch(() => undefined)
+      .then(task);
+
+    sessionData.pendingTask = nextTask.catch(() => undefined);
+    return nextTask;
+  }
+
+  clearSession(sessionKey: string): void {
+    const existed = this.sessions.has(sessionKey);
+    this.sessions.delete(sessionKey);
+
+    if (existed) {
+      this.logger.info(
+        "SessionBufferManager",
+        "Session cleared",
+        { sessionKey },
+        sessionKey
+      );
+    }
+  }
+
+  getSessionCount(): number {
+    return this.sessions.size;
+  }
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface Logger {
+  debug(
+    component: string,
+    event: string,
+    details?: Record<string, unknown>,
+    sessionKey?: string
+  ): void;
+  info(
+    component: string,
+    event: string,
+    details?: Record<string, unknown>,
+    sessionKey?: string
+  ): void;
+  warn(
+    component: string,
+    event: string,
+    details?: Record<string, unknown>,
+    sessionKey?: string
+  ): void;
+  error(
+    component: string,
+    event: string,
+    details?: Record<string, unknown>,
+    sessionKey?: string
+  ): void;
+}
+
+export interface ReflectionMessage {
+  id: string;
+  role: "user" | "agent";
+  message: string;
+  timestamp: number;
+  sessionKey: string;
+  channelId: string;
+  metadata?: {
+    from?: string;
+    to?: string;
+    messageId?: string;
+    success?: boolean;
+  };
+}
+
+export interface LogEntry {
+  timestamp: string;
+  level: LogLevel;
+  component: string;
+  sessionKey?: string;
+  event: string;
+  details?: Record<string, unknown>;
+}
+
+export type MemoryDecision =
+  | "NO_WRITE"
+  | "UPDATE_MEMORY"
+  | "UPDATE_USER"
+  | "UPDATE_SOUL"
+  | "UPDATE_IDENTITY"
+  | "UPDATE_TOOLS";
+
+export interface MemoryGateOutput {
+  decision: MemoryDecision;
+  reason: string;
+  candidateFact?: string;
+}
+
+export interface MemoryGateConfig {
+  enabled: boolean;
+  windowSize: number;
+}
+
+export interface ConsolidationConfig {
+  enabled: boolean;
+  schedule: string;
+}
+
+export interface LLMConfig {
+  baseURL: string;
+  apiKey: string;
+  model: string;
+}
+
+export interface PluginConfig {
+  bufferSize: number;
+  logLevel: LogLevel;
+  llm: LLMConfig;
+  memoryGate: MemoryGateConfig;
+  consolidation: ConsolidationConfig;
+}
+
+export type { MemoryGateInput } from "./memory-gate/types.js";
+export type {
+  AgentRunResult,
+  AgentStep,
+  AgentTool,
+  GenerateObjectParams,
+  JsonSchema,
+  LLMService,
+  LLMServiceConfig,
+  LLMServiceOptions,
+  RunAgentParams,
+} from "./llm/types.js";
+export type {
+  ConsolidatedFilename,
+  ConsolidationPatch,
+  ConsolidationProposal,
+  ConsolidationResult,
+} from "./consolidation/types.js";

package/src/utils/file-utils.ts

@@ -0,0 +1,228 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import lockfile from "proper-lockfile";
+
+const LOCK_TIMEOUT_MS = 5000;
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return typeof error === "object" && error !== null && "code" in error;
+}
+
+function formatDate(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}.md`;
+}
+
+async function createFileIfMissing(filePath: string): Promise<void> {
+  try {
+    await fs.access(filePath);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      const handle = await fs.open(filePath, "a");
+      await handle.close();
+      return;
+    }
+
+    throw error;
+  }
+}
+
+async function lockForWrite(filePath: string): Promise<() => Promise<void>> {
+  try {
+    await ensureDir(path.dirname(filePath));
+    await createFileIfMissing(filePath);
+
+    return await lockfile.lock(filePath, {
+      retries: {
+        retries: 5,
+        factor: 1,
+        minTimeout: 1000,
+        maxTimeout: 1000,
+        randomize: false,
+      },
+      stale: LOCK_TIMEOUT_MS,
+      realpath: false,
+    });
+  } catch (error) {
+    throw new Error(
+      `Failed to acquire lock for "${filePath}" within ${LOCK_TIMEOUT_MS}ms: ${getErrorMessage(error)}`
+    );
+  }
+}
+
+async function releaseLock(
+  release: () => Promise<void>,
+  filePath: string
+): Promise<void> {
+  try {
+    await release();
+  } catch (error) {
+    throw new Error(
+      `Failed to release lock for "${filePath}": ${getErrorMessage(error)}`
+    );
+  }
+}
+
+export async function ensureDir(dirPath: string): Promise<void> {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch (error) {
+    throw new Error(`Failed to ensure directory "${dirPath}": ${getErrorMessage(error)}`);
+  }
+}
+
+export async function readFile(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return null;
+    }
+
+    throw new Error(`Failed to read file "${filePath}": ${getErrorMessage(error)}`);
+  }
+}
+
+export async function writeFile(filePath: string, content: string): Promise<void> {
+  try {
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, content, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to write file "${filePath}": ${getErrorMessage(error)}`);
+  }
+}
+
+export async function writeFileWithLock(
+  filePath: string,
+  content: string
+): Promise<void> {
+  const release = await lockForWrite(filePath);
+  let writeError: unknown;
+
+  try {
+    await writeFile(filePath, content);
+  } catch (error) {
+    writeError = error;
+  }
+
+  try {
+    await releaseLock(release, filePath);
+  } catch (releaseError) {
+    if (writeError) {
+      throw new Error(
+        `Write and release failed for "${filePath}": write=${getErrorMessage(writeError)}; release=${getErrorMessage(releaseError)}`
+      );
+    }
+
+    throw releaseError;
+  }
+
+  if (writeError) {
+    throw new Error(
+      `Failed to write file with lock "${filePath}": ${getErrorMessage(writeError)}`
+    );
+  }
+}
+
+export async function appendFile(filePath: string, content: string): Promise<void> {
+  try {
+    await ensureDir(path.dirname(filePath));
+    await fs.appendFile(filePath, content, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to append file "${filePath}": ${getErrorMessage(error)}`);
+  }
+}
+
+export async function appendFileWithLock(
+  filePath: string,
+  content: string
+): Promise<void> {
+  const release = await lockForWrite(filePath);
+  let appendError: unknown;
+
+  try {
+    await appendFile(filePath, content);
+  } catch (error) {
+    appendError = error;
+  }
+
+  try {
+    await releaseLock(release, filePath);
+  } catch (releaseError) {
+    if (appendError) {
+      throw new Error(
+        `Append and release failed for "${filePath}": append=${getErrorMessage(appendError)}; release=${getErrorMessage(releaseError)}`
+      );
+    }
+
+    throw releaseError;
+  }
+
+  if (appendError) {
+    throw new Error(
+      `Failed to append file with lock "${filePath}": ${getErrorMessage(appendError)}`
+    );
+  }
+}
+
+export async function listFiles(dirPath: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    return entries
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (isNodeError(error) && error.code === "ENOENT") {
+      return [];
+    }
+
+    throw new Error(
+      `Failed to list files in "${dirPath}": ${getErrorMessage(error)}`
+    );
+  }
+}
+
+export async function moveFile(fromPath: string, toPath: string): Promise<void> {
+  try {
+    await ensureDir(path.dirname(toPath));
+    await fs.rename(fromPath, toPath);
+  } catch (error) {
+    if (isNodeError(error) && error.code === "EXDEV") {
+      try {
+        await fs.copyFile(fromPath, toPath);
+        await fs.unlink(fromPath);
+        return;
+      } catch (copyError) {
+        throw new Error(
+          `Failed to move file "${fromPath}" to "${toPath}": ${getErrorMessage(copyError)}`
+        );
+      }
+    }
+
+    throw new Error(
+      `Failed to move file "${fromPath}" to "${toPath}": ${getErrorMessage(error)}`
+    );
+  }
+}
+
+export function getTodayFilename(): string {
+  return formatDate(new Date());
+}
+
+export function getYesterdayFilename(): string {
+  const date = new Date();
+  date.setDate(date.getDate() - 1);
+  return formatDate(date);
+}