clawvault 2.0.2 → 2.1.1

package/dist/chunk-UPHUI5PD.js

@@ -0,0 +1,723 @@
+import {
+  getSessionsDir
+} from "./chunk-HRLWZGMA.js";
+import {
+  Observer,
+  parseSessionFile
+} from "./chunk-USAY3OIO.js";
+import {
+  resolveVaultPath
+} from "./chunk-MXSSG3QU.js";
+
+// src/commands/observe.ts
+import * as fs3 from "fs";
+import * as path3 from "path";
+import { spawn } from "child_process";
+
+// src/observer/watcher.ts
+import * as fs from "fs";
+import * as path from "path";
+import chokidar from "chokidar";
+var DEFAULT_FLUSH_THRESHOLD_CHARS = 500;
+var SessionWatcher = class {
+  watchPath;
+  observer;
+  ignoreInitial;
+  debounceMs;
+  flushThresholdChars;
+  watcher = null;
+  fileOffsets = /* @__PURE__ */ new Map();
+  pendingPaths = /* @__PURE__ */ new Set();
+  debounceTimer = null;
+  processingQueue = Promise.resolve();
+  bufferedChars = 0;
+  constructor(watchPath, observer, options = {}) {
+    this.watchPath = path.resolve(watchPath);
+    this.observer = observer;
+    this.ignoreInitial = options.ignoreInitial ?? false;
+    this.debounceMs = options.debounceMs ?? 500;
+    this.flushThresholdChars = Math.max(1, options.flushThresholdChars ?? DEFAULT_FLUSH_THRESHOLD_CHARS);
+  }
+  async start() {
+    if (!fs.existsSync(this.watchPath)) {
+      throw new Error(`Watch path does not exist: ${this.watchPath}`);
+    }
+    this.watcher = chokidar.watch(this.watchPath, {
+      persistent: true,
+      ignoreInitial: this.ignoreInitial,
+      awaitWriteFinish: {
+        stabilityThreshold: 120,
+        pollInterval: 30
+      }
+    });
+    const enqueue = (changedPath) => {
+      this.pendingPaths.add(path.resolve(changedPath));
+      this.scheduleDrain();
+    };
+    this.watcher.on("add", enqueue);
+    this.watcher.on("change", enqueue);
+    this.watcher.on("unlink", (deletedPath) => {
+      const resolved = path.resolve(deletedPath);
+      this.fileOffsets.delete(resolved);
+      this.pendingPaths.delete(resolved);
+    });
+    await new Promise((resolve4, reject) => {
+      this.watcher?.once("ready", () => resolve4());
+      this.watcher?.once("error", (error) => reject(error));
+    });
+    if (this.ignoreInitial) {
+      this.primeInitialOffsets();
+    }
+  }
+  async stop() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+      this.drainPendingPaths();
+    }
+    await this.processingQueue.catch(() => void 0);
+    if (this.bufferedChars > 0) {
+      await this.observer.flush();
+      this.bufferedChars = 0;
+    }
+    this.pendingPaths.clear();
+    await this.watcher?.close();
+    this.watcher = null;
+  }
+  scheduleDrain() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      this.drainPendingPaths();
+    }, this.debounceMs);
+  }
+  drainPendingPaths() {
+    const nextPaths = [...this.pendingPaths];
+    this.pendingPaths.clear();
+    for (const changedPath of nextPaths) {
+      this.processingQueue = this.processingQueue.then(() => this.consumeFile(changedPath)).catch(() => void 0);
+    }
+  }
+  async consumeFile(filePath) {
+    const resolved = path.resolve(filePath);
+    if (!fs.existsSync(resolved)) {
+      return;
+    }
+    const stats = fs.statSync(resolved);
+    if (!stats.isFile()) {
+      return;
+    }
+    const previousOffset = this.fileOffsets.get(resolved) ?? 0;
+    const startOffset = stats.size < previousOffset ? 0 : previousOffset;
+    if (stats.size <= startOffset) {
+      this.fileOffsets.set(resolved, stats.size);
+      return;
+    }
+    const bytesToRead = stats.size - startOffset;
+    const buffer = Buffer.alloc(bytesToRead);
+    const fd = fs.openSync(resolved, "r");
+    try {
+      fs.readSync(fd, buffer, 0, bytesToRead, startOffset);
+    } finally {
+      fs.closeSync(fd);
+    }
+    this.fileOffsets.set(resolved, stats.size);
+    const chunk = buffer.toString("utf-8");
+    const messages = chunk.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    if (messages.length === 0) {
+      return;
+    }
+    await this.observer.processMessages(messages);
+    this.bufferedChars += chunk.length;
+    if (this.bufferedChars >= this.flushThresholdChars) {
+      await this.observer.flush();
+      this.bufferedChars = 0;
+    }
+  }
+  primeInitialOffsets() {
+    for (const filePath of this.collectFiles(this.watchPath)) {
+      try {
+        const stats = fs.statSync(filePath);
+        if (stats.isFile()) {
+          this.fileOffsets.set(filePath, stats.size);
+        }
+      } catch {
+      }
+    }
+  }
+  collectFiles(targetPath) {
+    if (!fs.existsSync(targetPath)) {
+      return [];
+    }
+    const resolved = path.resolve(targetPath);
+    const stats = fs.statSync(resolved);
+    if (stats.isFile()) {
+      return [resolved];
+    }
+    if (!stats.isDirectory()) {
+      return [];
+    }
+    const collected = [];
+    for (const entry of fs.readdirSync(resolved, { withFileTypes: true })) {
+      const childPath = path.join(resolved, entry.name);
+      if (entry.isDirectory()) {
+        collected.push(...this.collectFiles(childPath));
+      } else if (entry.isFile()) {
+        collected.push(path.resolve(childPath));
+      }
+    }
+    return collected;
+  }
+};
+
+// src/observer/active-session-observer.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+var ONE_KIB = 1024;
+var ONE_MIB = ONE_KIB * ONE_KIB;
+var SMALL_SESSION_THRESHOLD_BYTES = 50 * ONE_KIB;
+var MEDIUM_SESSION_THRESHOLD_BYTES = 150 * ONE_KIB;
+var LARGE_SESSION_THRESHOLD_BYTES = 300 * ONE_KIB;
+var DEFAULT_AGENT_ID = "clawdious";
+var AGENT_ID_RE = /^[a-zA-Z0-9_-]{1,100}$/;
+var SESSION_ID_RE = /^[a-zA-Z0-9._-]{1,200}$/;
+var CURSOR_FILE_NAME = "observe-cursors.json";
+function isFiniteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function normalizeAgentId(input) {
+  const raw = (input ?? process.env.OPENCLAW_AGENT_ID ?? DEFAULT_AGENT_ID).trim();
+  if (!AGENT_ID_RE.test(raw)) {
+    return DEFAULT_AGENT_ID;
+  }
+  return raw;
+}
+function resolveSessionsDirectory(agentId, override) {
+  if (override?.trim()) {
+    return path2.resolve(override.trim());
+  }
+  return getSessionsDir(agentId);
+}
+function getCursorPath(vaultPath) {
+  return path2.join(vaultPath, ".clawvault", CURSOR_FILE_NAME);
+}
+function getScaledObservationThresholdBytes(fileSizeBytes) {
+  if (fileSizeBytes < ONE_MIB) {
+    return SMALL_SESSION_THRESHOLD_BYTES;
+  }
+  if (fileSizeBytes <= 5 * ONE_MIB) {
+    return MEDIUM_SESSION_THRESHOLD_BYTES;
+  }
+  return LARGE_SESSION_THRESHOLD_BYTES;
+}
+function parseCursorStore(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return {};
+  }
+  const input = raw;
+  const store = {};
+  for (const [sessionId, value] of Object.entries(input)) {
+    if (!SESSION_ID_RE.test(sessionId)) continue;
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const entry = value;
+    if (!isFiniteNonNegative(entry.lastObservedOffset)) continue;
+    if (!isFiniteNonNegative(entry.lastFileSize)) continue;
+    if (typeof entry.lastObservedAt !== "string" || !entry.lastObservedAt.trim()) continue;
+    if (typeof entry.sessionKey !== "string" || !entry.sessionKey.trim()) continue;
+    store[sessionId] = {
+      lastObservedOffset: entry.lastObservedOffset,
+      lastObservedAt: entry.lastObservedAt,
+      sessionKey: entry.sessionKey,
+      lastFileSize: entry.lastFileSize
+    };
+  }
+  return store;
+}
+function loadObserveCursorStore(vaultPath) {
+  const cursorPath = getCursorPath(vaultPath);
+  if (!fs2.existsSync(cursorPath)) {
+    return {};
+  }
+  try {
+    const raw = JSON.parse(fs2.readFileSync(cursorPath, "utf-8"));
+    return parseCursorStore(raw);
+  } catch {
+    return {};
+  }
+}
+function saveObserveCursorStore(vaultPath, store) {
+  const cursorPath = getCursorPath(vaultPath);
+  fs2.mkdirSync(path2.dirname(cursorPath), { recursive: true });
+  fs2.writeFileSync(cursorPath, `${JSON.stringify(store, null, 2)}
+`, "utf-8");
+}
+function loadSessionIndex(sessionsDir) {
+  const indexPath = path2.join(sessionsDir, "sessions.json");
+  if (!fs2.existsSync(indexPath)) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(fs2.readFileSync(indexPath, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed;
+  } catch {
+    return {};
+  }
+}
+function resolveTranscriptPath(sessionsDir, sessionId) {
+  return path2.join(sessionsDir, `${sessionId}.jsonl`);
+}
+function discoverSessionDescriptors(sessionsDir, fallbackAgentId) {
+  const descriptors = [];
+  const seen = /* @__PURE__ */ new Set();
+  const index = loadSessionIndex(sessionsDir);
+  const indexedEntries = Object.entries(index).sort((left, right) => {
+    const leftUpdated = Number(left[1]?.updatedAt ?? 0);
+    const rightUpdated = Number(right[1]?.updatedAt ?? 0);
+    return rightUpdated - leftUpdated;
+  });
+  for (const [sessionKey, entry] of indexedEntries) {
+    if (!entry || typeof entry !== "object") continue;
+    const sessionId = typeof entry.sessionId === "string" ? entry.sessionId.trim() : "";
+    if (!SESSION_ID_RE.test(sessionId) || seen.has(sessionId)) continue;
+    const filePath = resolveTranscriptPath(sessionsDir, sessionId);
+    try {
+      const stat = fs2.statSync(filePath);
+      if (!stat.isFile()) continue;
+      seen.add(sessionId);
+      descriptors.push({ sessionId, sessionKey, filePath });
+    } catch {
+      continue;
+    }
+  }
+  const fallbackPrefix = `agent:${fallbackAgentId}:`;
+  for (const fileName of fs2.readdirSync(sessionsDir)) {
+    if (!fileName.endsWith(".jsonl") || fileName.includes(".backup") || fileName.includes(".deleted")) {
+      continue;
+    }
+    const sessionId = fileName.slice(0, -".jsonl".length);
+    if (!SESSION_ID_RE.test(sessionId) || seen.has(sessionId)) continue;
+    const filePath = path2.join(sessionsDir, fileName);
+    try {
+      const stat = fs2.statSync(filePath);
+      if (!stat.isFile()) continue;
+      seen.add(sessionId);
+      descriptors.push({
+        sessionId,
+        sessionKey: `${fallbackPrefix}unknown:${sessionId}`,
+        filePath
+      });
+    } catch {
+      continue;
+    }
+  }
+  return descriptors;
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function extractContentText(value) {
+  if (typeof value === "string") {
+    return normalizeWhitespace(value);
+  }
+  if (Array.isArray(value)) {
+    const parts = value.map((item) => extractContentText(item)).filter(Boolean);
+    return normalizeWhitespace(parts.join(" "));
+  }
+  if (!value || typeof value !== "object") {
+    return "";
+  }
+  const input = value;
+  if (typeof input.text === "string") {
+    return normalizeWhitespace(input.text);
+  }
+  if (typeof input.content === "string") {
+    return normalizeWhitespace(input.content);
+  }
+  return "";
+}
+function normalizeRole(role) {
+  if (typeof role !== "string") {
+    return "";
+  }
+  return role.trim().toLowerCase();
+}
+function parseOpenClawJsonLine(line) {
+  if (!line.trim()) {
+    return "";
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return "";
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "";
+  }
+  const entry = parsed;
+  if ("role" in entry && "content" in entry) {
+    const role = normalizeRole(entry.role);
+    const content = extractContentText(entry.content);
+    if (!content) return "";
+    return role ? `${role}: ${content}` : content;
+  }
+  if (entry.type === "message" && entry.message && typeof entry.message === "object") {
+    const message = entry.message;
+    const role = normalizeRole(message.role);
+    const content = extractContentText(message.content);
+    if (!content) return "";
+    return role ? `${role}: ${content}` : content;
+  }
+  return "";
+}
+function decodeLineBuffer(lineBuffer) {
+  if (lineBuffer.length === 0) {
+    return "";
+  }
+  const normalized = lineBuffer[lineBuffer.length - 1] === 13 ? lineBuffer.subarray(0, lineBuffer.length - 1) : lineBuffer;
+  return normalized.toString("utf-8").trim();
+}
+async function readIncrementalMessages(filePath, startOffset) {
+  const messages = [];
+  let nextOffset = startOffset;
+  let remainder = Buffer.alloc(0);
+  const stream = fs2.createReadStream(filePath, {
+    start: startOffset
+  });
+  for await (const chunk of stream) {
+    const chunkBuffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    const combined = remainder.length > 0 ? Buffer.concat([remainder, chunkBuffer]) : chunkBuffer;
+    let lineStart = 0;
+    for (let index = 0; index < combined.length; index += 1) {
+      if (combined[index] !== 10) continue;
+      const lineBuffer = combined.subarray(lineStart, index);
+      const line = decodeLineBuffer(lineBuffer);
+      const parsed = parseOpenClawJsonLine(line);
+      if (parsed) {
+        messages.push(parsed);
+      }
+      nextOffset += index - lineStart + 1;
+      lineStart = index + 1;
+    }
+    remainder = combined.subarray(lineStart);
+  }
+  if (remainder.length > 0) {
+    const trailing = decodeLineBuffer(remainder);
+    if (trailing) {
+      const parsed = parseOpenClawJsonLine(trailing);
+      if (parsed) {
+        messages.push(parsed);
+        nextOffset += remainder.length;
+      }
+    }
+  }
+  return { messages, nextOffset };
+}
+function parseSessionSourceLabel(sessionKey) {
+  const parts = sessionKey.split(":");
+  if (parts.length < 3 || parts[0] !== "agent") {
+    return "session";
+  }
+  const scope = parts.slice(2);
+  if (scope[0] === "main") {
+    return "main";
+  }
+  if (scope[0] === "telegram" && scope[1] === "dm") {
+    return "telegram-dm";
+  }
+  if (scope[0] === "telegram" && scope[1] === "group") {
+    return "telegram-group";
+  }
+  if (scope[0] === "discord") {
+    return "discord";
+  }
+  if (scope[0] === "telegram") {
+    return "telegram";
+  }
+  if (scope[0] === "slack") {
+    return "slack";
+  }
+  return scope[0] || "session";
+}
+function createDefaultObserver(vaultPath, options) {
+  return new Observer(vaultPath, options);
+}
+function selectCandidates(descriptors, cursors, minNewBytes) {
+  const candidates = [];
+  for (const descriptor of descriptors) {
+    let stat;
+    try {
+      stat = fs2.statSync(descriptor.filePath);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    const fileSize = stat.size;
+    const cursor = cursors[descriptor.sessionId];
+    const previousOffset = cursor && isFiniteNonNegative(cursor.lastObservedOffset) ? cursor.lastObservedOffset : 0;
+    const startOffset = previousOffset <= fileSize ? previousOffset : 0;
+    const newBytes = Math.max(0, fileSize - startOffset);
+    const thresholdBytes = minNewBytes ?? getScaledObservationThresholdBytes(fileSize);
+    if (newBytes < thresholdBytes) {
+      continue;
+    }
+    candidates.push({
+      sessionId: descriptor.sessionId,
+      sessionKey: descriptor.sessionKey,
+      sourceLabel: parseSessionSourceLabel(descriptor.sessionKey),
+      filePath: descriptor.filePath,
+      fileSize,
+      startOffset,
+      newBytes,
+      thresholdBytes
+    });
+  }
+  return candidates;
+}
+async function observeActiveSessions(options, dependencies = {}) {
+  const vaultPath = path2.resolve(options.vaultPath);
+  const agentId = normalizeAgentId(options.agentId);
+  const sessionsDir = resolveSessionsDirectory(agentId, options.sessionsDir);
+  const dryRun = Boolean(options.dryRun);
+  if (!fs2.existsSync(sessionsDir) || !fs2.statSync(sessionsDir).isDirectory()) {
+    return {
+      agentId,
+      sessionsDir,
+      checkedSessions: 0,
+      candidateSessions: 0,
+      observedSessions: 0,
+      cursorUpdates: 0,
+      dryRun,
+      totalNewBytes: 0,
+      candidates: []
+    };
+  }
+  const now = dependencies.now ?? (() => /* @__PURE__ */ new Date());
+  const cursors = loadObserveCursorStore(vaultPath);
+  const descriptors = discoverSessionDescriptors(sessionsDir, agentId);
+  const candidates = selectCandidates(descriptors, cursors, options.minNewBytes);
+  if (dryRun || candidates.length === 0) {
+    return {
+      agentId,
+      sessionsDir,
+      checkedSessions: descriptors.length,
+      candidateSessions: candidates.length,
+      observedSessions: 0,
+      cursorUpdates: 0,
+      dryRun,
+      totalNewBytes: candidates.reduce((sum, candidate) => sum + candidate.newBytes, 0),
+      candidates
+    };
+  }
+  const observerFactory = dependencies.createObserver ?? createDefaultObserver;
+  const observer = observerFactory(vaultPath, {
+    tokenThreshold: options.threshold,
+    reflectThreshold: options.reflectThreshold,
+    model: options.model
+  });
+  let observedSessions = 0;
+  let cursorUpdates = 0;
+  for (const candidate of candidates) {
+    const { messages, nextOffset } = await readIncrementalMessages(candidate.filePath, candidate.startOffset);
+    const taggedMessages = messages.map((message) => `[${candidate.sourceLabel}] ${message}`);
+    if (taggedMessages.length > 0) {
+      await observer.processMessages(taggedMessages);
+      await observer.flush();
+      observedSessions += 1;
+    }
+    if (nextOffset > candidate.startOffset) {
+      cursors[candidate.sessionId] = {
+        lastObservedOffset: nextOffset,
+        lastObservedAt: now().toISOString(),
+        sessionKey: candidate.sessionKey,
+        lastFileSize: candidate.fileSize
+      };
+      cursorUpdates += 1;
+    }
+  }
+  if (cursorUpdates > 0) {
+    saveObserveCursorStore(vaultPath, cursors);
+  }
+  return {
+    agentId,
+    sessionsDir,
+    checkedSessions: descriptors.length,
+    candidateSessions: candidates.length,
+    observedSessions,
+    cursorUpdates,
+    dryRun,
+    totalNewBytes: candidates.reduce((sum, candidate) => sum + candidate.newBytes, 0),
+    candidates
+  };
+}
+
+// src/commands/observe.ts
+function parsePositiveInteger(raw, optionName) {
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${optionName}: ${raw}`);
+  }
+  return parsed;
+}
+function buildDaemonArgs(options) {
+  const cliPath = process.argv[1];
+  if (!cliPath) {
+    throw new Error("Unable to resolve CLI script path for daemon mode.");
+  }
+  const args = [cliPath, "observe"];
+  if (options.watch) {
+    args.push("--watch", options.watch);
+  }
+  if (options.threshold) {
+    args.push("--threshold", String(options.threshold));
+  }
+  if (options.reflectThreshold) {
+    args.push("--reflect-threshold", String(options.reflectThreshold));
+  }
+  if (options.model) {
+    args.push("--model", options.model);
+  }
+  if (options.vaultPath) {
+    args.push("--vault", options.vaultPath);
+  }
+  return args;
+}
+async function runOneShotCompression(observer, sourceFile, vaultPath) {
+  const resolved = path3.resolve(sourceFile);
+  if (!fs3.existsSync(resolved) || !fs3.statSync(resolved).isFile()) {
+    throw new Error(`Conversation file not found: ${resolved}`);
+  }
+  const messages = parseSessionFile(resolved);
+  await observer.processMessages(messages);
+  const { observations, routingSummary } = await observer.flush();
+  const datePart = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const outputPath = path3.join(vaultPath, "observations", `${datePart}.md`);
+  console.log(`Observations updated: ${outputPath}`);
+  if (routingSummary) {
+    console.log(routingSummary);
+  }
+}
+async function watchSessions(observer, watchPath) {
+  const watcher = new SessionWatcher(watchPath, observer);
+  await watcher.start();
+  console.log(`Watching session updates: ${watchPath}`);
+  await new Promise((resolve4) => {
+    const shutdown = async () => {
+      process.off("SIGINT", onSigInt);
+      process.off("SIGTERM", onSigTerm);
+      await watcher.stop();
+      resolve4();
+    };
+    const onSigInt = () => {
+      void shutdown();
+    };
+    const onSigTerm = () => {
+      void shutdown();
+    };
+    process.once("SIGINT", onSigInt);
+    process.once("SIGTERM", onSigTerm);
+  });
+}
+async function observeCommand(options) {
+  if (options.active && (options.watch || options.compress || options.daemon)) {
+    throw new Error("--active cannot be combined with --watch, --compress, or --daemon.");
+  }
+  if (options.compress && options.daemon) {
+    throw new Error("--compress cannot be combined with --daemon.");
+  }
+  const vaultPath = resolveVaultPath({ explicitPath: options.vaultPath });
+  if (options.active) {
+    const result = await observeActiveSessions({
+      vaultPath,
+      agentId: options.agent,
+      minNewBytes: options.minNew,
+      sessionsDir: options.sessionsDir,
+      dryRun: options.dryRun,
+      threshold: options.threshold,
+      reflectThreshold: options.reflectThreshold,
+      model: options.model
+    });
+    if (result.candidateSessions === 0) {
+      console.log(`No active sessions crossed threshold (${result.checkedSessions} checked).`);
+      return;
+    }
+    if (result.dryRun) {
+      console.log(
+        `Dry run: ${result.candidateSessions} session(s) would be observed (${result.totalNewBytes} new bytes).`
+      );
+      for (const candidate of result.candidates) {
+        console.log(
+          `- ${candidate.sessionKey} [${candidate.sourceLabel}] \u0394${candidate.newBytes}B (threshold ${candidate.thresholdBytes}B)`
+        );
+      }
+      return;
+    }
+    console.log(
+      `Active observation complete: ${result.observedSessions}/${result.candidateSessions} session(s) observed.`
+    );
+    return;
+  }
+  const observer = new Observer(vaultPath, {
+    tokenThreshold: options.threshold,
+    reflectThreshold: options.reflectThreshold,
+    model: options.model
+  });
+  if (options.compress) {
+    await runOneShotCompression(observer, options.compress, vaultPath);
+    return;
+  }
+  let watchPath = options.watch ? path3.resolve(options.watch) : "";
+  if (!watchPath && options.daemon) {
+    watchPath = path3.join(vaultPath, "sessions");
+  }
+  if (!watchPath) {
+    throw new Error("Either --watch or --compress must be provided.");
+  }
+  if (!fs3.existsSync(watchPath)) {
+    if (options.daemon && !options.watch) {
+      fs3.mkdirSync(watchPath, { recursive: true });
+    } else {
+      throw new Error(`Watch path does not exist: ${watchPath}`);
+    }
+  }
+  if (options.daemon) {
+    const daemonArgs = buildDaemonArgs({ ...options, watch: watchPath, vaultPath });
+    const child = spawn(process.execPath, daemonArgs, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+    console.log(`Observer daemon started (pid: ${child.pid})`);
+    return;
+  }
+  await watchSessions(observer, watchPath);
+}
+function registerObserveCommand(program) {
+  program.command("observe").description("Observe session files and build observational memory").option("--watch <path>", "Watch session file or directory").option("--active", "Observe active OpenClaw sessions incrementally").option("--agent <id>", "OpenClaw agent ID (default: OPENCLAW_AGENT_ID or clawdious)").option("--min-new <bytes>", "Override minimum new-content threshold in bytes").option("--sessions-dir <path>", "Override OpenClaw sessions directory").option("--dry-run", "Show active observation candidates without compressing").option("--threshold <n>", "Compression token threshold", "30000").option("--reflect-threshold <n>", "Reflection token threshold", "40000").option("--model <model>", "LLM model override").option("--compress <file>", "One-shot compression for a conversation file").option("--daemon", "Run in detached background mode").option("-v, --vault <path>", "Vault path").action(async (rawOptions) => {
+    await observeCommand({
+      watch: rawOptions.watch,
+      active: rawOptions.active,
+      agent: rawOptions.agent,
+      minNew: rawOptions.minNew ? parsePositiveInteger(rawOptions.minNew, "min-new") : void 0,
+      sessionsDir: rawOptions.sessionsDir,
+      dryRun: rawOptions.dryRun,
+      threshold: parsePositiveInteger(rawOptions.threshold, "threshold"),
+      reflectThreshold: parsePositiveInteger(rawOptions.reflectThreshold, "reflect-threshold"),
+      model: rawOptions.model,
+      compress: rawOptions.compress,
+      daemon: rawOptions.daemon,
+      vaultPath: rawOptions.vault
+    });
+  });
+}
+
+export {
+  SessionWatcher,
+  observeCommand,
+  registerObserveCommand
+};