ocuclaw 0.1.0

package/dist/domain/debug-store.js

@@ -0,0 +1,700 @@
+const DEFAULT_DEBUG_CATEGORIES = Object.freeze([
+  "relay.transport",
+  "relay.protocol",
+  "relay.session",
+  "openclaw.run",
+  "openclaw.seq",
+  "openclaw.history",
+  "sdk.frames",
+  "sdk.results",
+  "sdk.events",
+  "sdk.events.summary",
+  "sdk.events.raw",
+  "app.timeline",
+  "app.lifecycle",
+  "probe.runtime.main_thread",
+  "probe.runtime.memory",
+  "probe.runtime.bridge",
+  "probe.runtime.bridge_timing",
+  "probe.runtime.screen_off",
+  "probe.perf.conversation_upgrade",
+  "app.state.diff",
+  "render.ownership",
+  "render.virtual_pager",
+  "render.virtual_pager.summary",
+  "render.virtual_pager.diagnostics",
+  "screen.nav",
+  "screen.dim",
+  "probe.webview.trace",
+  "session.timeline",
+  "approvals.timeline",
+  "approvals.state",
+  "voice.timeline",
+  "voice.transport",
+  "evenai",
+  "audio.pipeline",
+  "settings.loadsave",
+  "config.timeline",
+  "workflow.profile",
+  "workflow.run",
+]);
+
+const DEBUG_CATEGORY_ALIASES = Object.freeze({
+  "app.timeline": Object.freeze([
+    "app.timeline",
+    "app.lifecycle",
+    "probe.runtime.main_thread",
+    "probe.runtime.memory",
+    "probe.runtime.bridge",
+    "probe.runtime.bridge_timing",
+    "probe.runtime.screen_off",
+    "probe.perf.conversation_upgrade",
+  ]),
+  "voice.timeline": Object.freeze([
+    "voice.timeline",
+    "voice.transport",
+  ]),
+  "sdk.events": Object.freeze([
+    "sdk.events",
+    "sdk.events.summary",
+    "sdk.events.raw",
+  ]),
+  "render.virtual_pager": Object.freeze([
+    "render.virtual_pager",
+    "render.virtual_pager.summary",
+    "render.virtual_pager.diagnostics",
+  ]),
+});
+
+const DEFAULT_NOISY_CATEGORY_POLICIES = Object.freeze({
+  "sdk.frames": Object.freeze({
+    sampleEvery: 5,
+    dedupeWindowMs: 150,
+    alwaysAllow: Object.freeze([
+      "coalescing_summary",
+      "stream_first_visible_latency_v1",
+    ]),
+  }),
+  "audio.pipeline": Object.freeze({
+    sampleEvery: 5,
+    dedupeWindowMs: 150,
+  }),
+});
+
+const REDACTION_SAFE = "safe";
+const REDACTION_FULL = "full";
+const DEFAULT_REDACTION_MODE = REDACTION_SAFE;
+const SUPPORTED_REDACTION_MODES = new Set([
+  REDACTION_SAFE,
+  REDACTION_FULL,
+]);
+const SENSITIVE_KEY_PATTERN =
+  /(?:api[-_]?key|auth(?:orization)?|bearer|cookie|credential|jwt|pass(?:word|phrase)?|private[-_]?key|secret|signature|token)/i;
+const FULL_ONLY_KEY_PATTERN =
+  /^(?:renderedtext|fulltext|screentext)$/i;
+const SECRET_VALUE_PATTERN =
+  /(?:^sk-[A-Za-z0-9_-]{8,}$)|(?:^Bearer\s+[^\s]+$)|(?:eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,})/;
+const MAX_REDACTION_DEPTH = 6;
+
+function clampInt(value, min, max, fallback) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  const rounded = Math.floor(n);
+  if (rounded < min) return min;
+  if (rounded > max) return max;
+  return rounded;
+}
+
+function normalizeCategoryList(raw) {
+  if (!Array.isArray(raw)) return [];
+  const dedup = new Set();
+  for (const entry of raw) {
+    if (typeof entry !== "string") continue;
+    const cat = entry.trim();
+    if (!cat) continue;
+    dedup.add(cat);
+  }
+  return Array.from(dedup.values());
+}
+
+function expandCategoryAliases(list) {
+  if (!Array.isArray(list) || list.length === 0) {
+    return [];
+  }
+  const dedup = new Set();
+  for (const category of list) {
+    const expanded = DEBUG_CATEGORY_ALIASES[category] || [category];
+    for (const entry of expanded) {
+      if (typeof entry !== "string" || !entry) continue;
+      dedup.add(entry);
+    }
+  }
+  return Array.from(dedup.values());
+}
+
+function normalizeRedactionMode(raw) {
+  if (raw === undefined || raw === null) return DEFAULT_REDACTION_MODE;
+  if (typeof raw !== "string") return null;
+  const mode = raw.trim().toLowerCase();
+  if (!mode) return DEFAULT_REDACTION_MODE;
+  if (!SUPPORTED_REDACTION_MODES.has(mode)) return null;
+  return mode;
+}
+
+function createDebugStore(opts) {
+  const options = opts || {};
+  const capacity = clampInt(options.capacity, 1, 50000, 5000);
+  const payloadMaxBytes = clampInt(options.payloadMaxBytes, 256, 65536, 2048);
+  const defaultTtlMs = clampInt(options.defaultTtlMs, 1, 600000, 120000);
+  const maxTtlMs = clampInt(options.maxTtlMs, 1, 3600000, 600000);
+  const dumpDefaultLimit = clampInt(options.dumpDefaultLimit, 1, 2000, 300);
+  const dumpMaxLimit = clampInt(options.dumpMaxLimit, 1, 10000, 2000);
+  const nowFn = typeof options.now === "function" ? options.now : () => Date.now();
+
+  const configuredCategories =
+    Array.isArray(options.categories) && options.categories.length > 0
+      ? normalizeCategoryList(options.categories)
+      : DEFAULT_DEBUG_CATEGORIES;
+  const categories = new Set(configuredCategories);
+
+  const noisyPolicies = {
+    ...DEFAULT_NOISY_CATEGORY_POLICIES,
+    ...(options.noisyPolicies || {}),
+  };
+  const safeStringTailChars = clampInt(
+    options.safeStringTailChars,
+    16,
+    2048,
+    Math.max(64, Math.min(payloadMaxBytes, 160)),
+  );
+  const fullStringTailChars = clampInt(
+    options.fullStringTailChars,
+    safeStringTailChars,
+    4096,
+    Math.max(256, Math.min(payloadMaxBytes * 2, 1024)),
+  );
+
+  /** @type {Map<string, number>} */
+  const enabledUntil = new Map();
+
+  /** @type {Map<string, number>} */
+  const noisyCounters = new Map();
+
+  /** @type {Map<string, { key: string, ts: number }>} */
+  const noisyLast = new Map();
+
+  /** @type {Array<object>} */
+  const ring = new Array(capacity);
+  let ringWrite = 0;
+  let ringSize = 0;
+  let seq = 0;
+
+function isSensitiveKeyName(keyName) {
+  if (typeof keyName !== "string" || !keyName) return false;
+  return SENSITIVE_KEY_PATTERN.test(keyName);
+}
+
+function isFullOnlyKeyName(keyName) {
+  if (typeof keyName !== "string" || !keyName) return false;
+  return FULL_ONLY_KEY_PATTERN.test(keyName);
+}
+
+function redactInlineSecrets(value) {
+    if (typeof value !== "string" || !value) return value;
+    return value
+      .replace(/(Bearer\s+)[^\s"']+/gi, "$1[REDACTED]")
+      .replace(
+        /((?:api[-_]?key|token|secret|password|passphrase)\s*(?:=|:)\s*)([^,\s"']+)/gi,
+        "$1[REDACTED]",
+      );
+  }
+
+function redactStringValue(value, mode, keyName) {
+  const sensitiveByKey = isSensitiveKeyName(keyName);
+  if (mode === REDACTION_SAFE) {
+    if (isFullOnlyKeyName(keyName)) {
+      return {
+        _fullOnly: true,
+        _chars: value.length,
+      };
+    }
+    if (sensitiveByKey || SECRET_VALUE_PATTERN.test(value)) {
+      return "[REDACTED]";
+    }
+      const redactedInline = redactInlineSecrets(value);
+      if (redactedInline.length <= safeStringTailChars) {
+        return redactedInline;
+      }
+      return {
+        _truncated: true,
+        _chars: redactedInline.length,
+        _tail: redactedInline.slice(-safeStringTailChars),
+      };
+    }
+
+    if (value.length <= fullStringTailChars) {
+      return value;
+    }
+    return {
+      _truncated: true,
+      _chars: value.length,
+      _tail: value.slice(-fullStringTailChars),
+    };
+  }
+
+  function redactDataByMode(value, mode, keyName, depth) {
+    if (depth > MAX_REDACTION_DEPTH) {
+      return { _truncated: true, _depth: depth };
+    }
+
+    if (typeof value === "string") {
+      return redactStringValue(value, mode, keyName);
+    }
+    if (
+      value === null ||
+      typeof value === "number" ||
+      typeof value === "boolean"
+    ) {
+      return value;
+    }
+    if (Array.isArray(value)) {
+      return value.map((entry) =>
+        redactDataByMode(entry, mode, keyName, depth + 1),
+      );
+    }
+    if (typeof value === "object") {
+      const out = {};
+      for (const [key, entry] of Object.entries(value)) {
+        out[key] = redactDataByMode(entry, mode, key, depth + 1);
+      }
+      return out;
+    }
+
+    return { value };
+  }
+
+  function buildRedactedDataModes(data) {
+    const safe = redactDataByMode(data, REDACTION_SAFE, null, 0);
+    const full = redactDataByMode(data, REDACTION_FULL, null, 0);
+    let safeSerialized;
+    try {
+      safeSerialized = JSON.stringify(safe);
+    } catch {
+      safeSerialized = "{\"_serializationError\":true}";
+    }
+    return { safe, full, safeSerialized };
+  }
+
+  function pruneExpired(nowMs) {
+    for (const [cat, expiresAt] of enabledUntil) {
+      if (expiresAt <= nowMs) {
+        enabledUntil.delete(cat);
+      }
+    }
+  }
+
+  function getEnabledCategories(nowMs) {
+    const ts = Number.isFinite(nowMs) ? nowMs : nowFn();
+    pruneExpired(ts);
+    return Array.from(enabledUntil.entries())
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([cat, expiresAtMs]) => ({ cat, expiresAtMs }));
+  }
+
+  function isEnabled(category, nowMs) {
+    if (typeof category !== "string" || !category) return false;
+    const ts = Number.isFinite(nowMs) ? nowMs : nowFn();
+    const expiresAt = enabledUntil.get(category);
+    if (!expiresAt) return false;
+    if (expiresAt <= ts) {
+      enabledUntil.delete(category);
+      return false;
+    }
+    return true;
+  }
+
+  function unknownCategories(list) {
+    const unknown = [];
+    for (const cat of list) {
+      if (!categories.has(cat)) unknown.push(cat);
+    }
+    return unknown;
+  }
+
+  function setCategories(request) {
+    const req = request || {};
+    const enable = expandCategoryAliases(normalizeCategoryList(req.enable));
+    const disable = expandCategoryAliases(normalizeCategoryList(req.disable));
+    const nowMs = nowFn();
+
+    if (enable.length === 0 && disable.length === 0) {
+      return {
+        ok: false,
+        error: "debug-set requires at least one category in enable or disable",
+      };
+    }
+
+    const overlap = enable.filter((cat) => disable.includes(cat));
+    if (overlap.length > 0) {
+      return {
+        ok: false,
+        error: `debug-set category cannot be both enabled and disabled: ${overlap.join(", ")}`,
+      };
+    }
+
+    const unknown = unknownCategories([...enable, ...disable]);
+    if (unknown.length > 0) {
+      return {
+        ok: false,
+        error: `Unknown debug categories: ${unknown.join(", ")}`,
+      };
+    }
+
+    let ttlMs = null;
+    let expiresAtMs = null;
+    if (enable.length > 0) {
+      const rawTtl = req.ttlMs === undefined || req.ttlMs === null ? defaultTtlMs : Number(req.ttlMs);
+      if (!Number.isFinite(rawTtl) || rawTtl <= 0) {
+        return {
+          ok: false,
+          error: "debug-set ttlMs must be a positive number",
+        };
+      }
+      ttlMs = Math.min(Math.floor(rawTtl), maxTtlMs);
+      expiresAtMs = nowMs + ttlMs;
+      for (const cat of enable) {
+        enabledUntil.set(cat, expiresAtMs);
+      }
+    }
+
+    if (disable.length > 0) {
+      for (const cat of disable) {
+        enabledUntil.delete(cat);
+      }
+    }
+
+    return {
+      ok: true,
+      nowMs,
+      ttlMs,
+      expiresAtMs,
+      applied: { enable, disable },
+      enabled: getEnabledCategories(nowMs),
+    };
+  }
+
+  function normalizeData(data) {
+    let normalized = data;
+    if (normalized === undefined) {
+      normalized = {};
+    } else if (
+      normalized === null ||
+      typeof normalized !== "object" ||
+      Array.isArray(normalized)
+    ) {
+      normalized = { value: normalized };
+    }
+
+    let serialized;
+    try {
+      serialized = JSON.stringify(normalized);
+    } catch {
+      normalized = { _serializationError: true };
+      serialized = JSON.stringify(normalized);
+    }
+
+    const bytes = Buffer.byteLength(serialized, "utf8");
+    if (bytes <= payloadMaxBytes) {
+      return { data: normalized, serialized };
+    }
+
+    const tailMaxChars = Math.max(64, Math.min(payloadMaxBytes, 1024));
+    const truncated = {
+      _truncated: true,
+      _bytes: bytes,
+      _tail: serialized.slice(-tailMaxChars),
+    };
+    return {
+      data: truncated,
+      serialized: JSON.stringify(truncated),
+    };
+  }
+
+  function allowByNoisyPolicy(cat, eventName, serializedData, ts) {
+    const rawPolicy = noisyPolicies[cat];
+    if (!rawPolicy) return true;
+
+    const alwaysAllow = rawPolicy.alwaysAllow;
+    if (Array.isArray(alwaysAllow) && alwaysAllow.includes(eventName)) {
+      return true;
+    }
+
+    const sampleEvery = clampInt(rawPolicy.sampleEvery, 1, 1000, 1);
+    const dedupeWindowMs = clampInt(rawPolicy.dedupeWindowMs, 0, 60000, 0);
+
+    const nextCount = (noisyCounters.get(cat) || 0) + 1;
+    noisyCounters.set(cat, nextCount);
+    if (sampleEvery > 1 && nextCount % sampleEvery !== 1) {
+      return false;
+    }
+
+    if (dedupeWindowMs > 0) {
+      const key = `${eventName}|${serializedData.slice(0, 160)}`;
+      const prev = noisyLast.get(cat);
+      if (prev && prev.key === key && ts - prev.ts <= dedupeWindowMs) {
+        return false;
+      }
+      noisyLast.set(cat, { key, ts });
+    }
+
+    return true;
+  }
+
+  function append(event) {
+    ring[ringWrite] = event;
+    ringWrite = (ringWrite + 1) % capacity;
+    if (ringSize < capacity) {
+      ringSize += 1;
+    }
+  }
+
+  function emit(event) {
+    const raw = event || {};
+    const cat = typeof raw.cat === "string" ? raw.cat.trim() : "";
+    if (!cat) return false;
+    if (!isEnabled(cat)) return false;
+
+    const ts = Number.isFinite(raw.ts) ? Math.floor(raw.ts) : nowFn();
+    const eventName =
+      typeof raw.event === "string" && raw.event.trim()
+        ? raw.event.trim()
+        : "event";
+    const severity =
+      raw.severity === "info" ||
+      raw.severity === "warn" ||
+      raw.severity === "error"
+        ? raw.severity
+        : "debug";
+
+    const normalized = normalizeData(raw.data);
+    const redactedDataModes = buildRedactedDataModes(normalized.data);
+    if (!allowByNoisyPolicy(cat, eventName, redactedDataModes.safeSerialized, ts)) {
+      return false;
+    }
+
+    const out = {
+      ts,
+      cat,
+      event: eventName,
+      severity,
+      seq: ++seq,
+      dataSafe: redactedDataModes.safe,
+      dataFull: redactedDataModes.full,
+    };
+
+    if (typeof raw.sessionKey === "string" && raw.sessionKey) {
+      out.sessionKey = raw.sessionKey;
+    }
+    if (typeof raw.runId === "string" && raw.runId) {
+      out.runId = raw.runId;
+    }
+    if (typeof raw.screen === "string" && raw.screen) {
+      out.screen = raw.screen;
+    }
+
+    append(out);
+    return true;
+  }
+
+  function getAllEvents() {
+    if (ringSize === 0) return [];
+    const out = [];
+    const oldest = (ringWrite - ringSize + capacity) % capacity;
+    for (let i = 0; i < ringSize; i += 1) {
+      out.push(ring[(oldest + i) % capacity]);
+    }
+    return out;
+  }
+
+  function formatEventForDump(evt, redactionMode) {
+    const out = {
+      ts: evt.ts,
+      cat: evt.cat,
+      event: evt.event,
+      severity: evt.severity,
+      seq: evt.seq,
+      data:
+        redactionMode === REDACTION_FULL
+          ? evt.dataFull
+          : evt.dataSafe,
+    };
+
+    if (typeof evt.sessionKey === "string" && evt.sessionKey) {
+      out.sessionKey = evt.sessionKey;
+    }
+    if (typeof evt.runId === "string" && evt.runId) {
+      out.runId = evt.runId;
+    }
+    if (typeof evt.screen === "string" && evt.screen) {
+      out.screen = evt.screen;
+    }
+
+    return out;
+  }
+
+  function dump(request) {
+    const req = request || {};
+    const nowMs = nowFn();
+    const redaction = normalizeRedactionMode(req.redaction);
+    if (!redaction) {
+      return {
+        ok: false,
+        error: "debug-dump redaction must be one of: safe, full",
+      };
+    }
+    const categoriesFilter = expandCategoryAliases(
+      normalizeCategoryList(req.categories),
+    );
+    const unknown = unknownCategories(categoriesFilter);
+    if (unknown.length > 0) {
+      return {
+        ok: false,
+        error: `Unknown debug categories: ${unknown.join(", ")}`,
+      };
+    }
+
+    if (
+      req.limit !== undefined &&
+      (!Number.isFinite(Number(req.limit)) || Number(req.limit) <= 0)
+    ) {
+      return {
+        ok: false,
+        error: "debug-dump limit must be a positive number",
+      };
+    }
+
+    if (
+      req.sinceMs !== undefined &&
+      (!Number.isFinite(Number(req.sinceMs)) || Number(req.sinceMs) < 0)
+    ) {
+      return {
+        ok: false,
+        error: "debug-dump sinceMs must be a non-negative number",
+      };
+    }
+
+    if (
+      req.sinceAgeMs !== undefined &&
+      (!Number.isFinite(Number(req.sinceAgeMs)) || Number(req.sinceAgeMs) < 0)
+    ) {
+      return {
+        ok: false,
+        error: "debug-dump sinceAgeMs must be a non-negative number",
+      };
+    }
+
+    if (
+      req.untilMs !== undefined &&
+      (!Number.isFinite(Number(req.untilMs)) || Number(req.untilMs) < 0)
+    ) {
+      return {
+        ok: false,
+        error: "debug-dump untilMs must be a non-negative number",
+      };
+    }
+
+    const limit = clampInt(req.limit, 1, dumpMaxLimit, dumpDefaultLimit);
+    const sinceMs =
+      req.sinceMs !== undefined
+        ? Math.floor(Number(req.sinceMs))
+        : req.sinceAgeMs !== undefined
+          ? nowMs - Math.floor(Number(req.sinceAgeMs))
+          : null;
+    const untilMs =
+      req.untilMs !== undefined ? Math.floor(Number(req.untilMs)) : null;
+
+    if (
+      sinceMs !== null &&
+      untilMs !== null &&
+      Number.isFinite(sinceMs) &&
+      Number.isFinite(untilMs) &&
+      untilMs < sinceMs
+    ) {
+      return {
+        ok: false,
+        error: "debug-dump untilMs must be greater than or equal to sinceMs",
+      };
+    }
+
+    const categorySet =
+      categoriesFilter.length > 0 ? new Set(categoriesFilter) : null;
+    const filtered = [];
+    const all = getAllEvents();
+    for (const evt of all) {
+      if (categorySet && !categorySet.has(evt.cat)) continue;
+      if (sinceMs !== null && evt.ts < sinceMs) continue;
+      if (untilMs !== null && evt.ts > untilMs) continue;
+      filtered.push(evt);
+    }
+
+    const events =
+      filtered.length > limit
+        ? filtered.slice(filtered.length - limit)
+        : filtered;
+    const formattedEvents = events.map((evt) =>
+      formatEventForDump(evt, redaction),
+    );
+
+    return {
+      ok: true,
+      nowMs,
+      sinceMs,
+      untilMs,
+      redaction,
+      categories: categoriesFilter,
+      limit,
+      totalMatched: filtered.length,
+      returned: formattedEvents.length,
+      dropped: Math.max(0, filtered.length - formattedEvents.length),
+      enabled: getEnabledCategories(nowMs),
+      events: formattedEvents,
+    };
+  }
+
+  function getSnapshot(nowMs) {
+    const serverNowMs = Number.isFinite(nowMs) ? Math.floor(nowMs) : nowFn();
+    return {
+      serverNowMs,
+      enabled: getEnabledCategories(serverNowMs),
+    };
+  }
+
+  return {
+    setCategories,
+    dump,
+    emit,
+    isEnabled,
+    getSnapshot,
+    getEnabledCategories,
+    getKnownCategories() {
+      return Array.from(categories.values()).sort();
+    },
+    getConfig() {
+      return {
+        capacity,
+        payloadMaxBytes,
+        defaultTtlMs,
+        maxTtlMs,
+        dumpDefaultLimit,
+        dumpMaxLimit,
+        defaultRedaction: DEFAULT_REDACTION_MODE,
+      };
+    },
+  };
+}
+
+export {
+  createDebugStore,
+  DEFAULT_DEBUG_CATEGORIES,
+  DEFAULT_NOISY_CATEGORY_POLICIES,
+};