ocuclaw 1.3.1 → 1.3.3

package/dist/runtime/display-toggle-states.js

@@ -0,0 +1,98 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const DEFAULTS = { emoji: false, pace: false };
+const STORE_FILENAME = "ocuclaw-display-toggles.json";
+
+/**
+ * Tracks, per session, the display-feature toggle state at session start
+ * (frozen on first record) and the latest reported state.
+ *
+ * The FROZEN start-state is persisted to stateDir so it survives a relay/plugin
+ * restart — the Channel-1 prompt snapshot is also persisted, so without this the
+ * Channel-2 disable stop-notice would be lost after a restart (a session that
+ * started with a feature ON would re-freeze start=OFF from the first post-restart
+ * send and never notice the disable). The CURRENT state is NOT persisted: it
+ * re-derives from the next send, so persisting it would mean a write per turn.
+ */
+export function createDisplayToggleTracker(opts = {}) {
+  const limit = Number.isFinite(opts.limit) ? opts.limit : 200;
+  const statePath =
+    typeof opts.stateDir === "string" && opts.stateDir.trim()
+      ? path.join(opts.stateDir.trim(), STORE_FILENAME)
+      : null;
+  /** @type {Map<string,{start:{emoji,pace},current:{emoji,pace}}>} */
+  const byKey = new Map();
+
+  function norm(v) {
+    return { emoji: !!(v && v.emoji), pace: !!(v && v.pace) };
+  }
+
+  function load() {
+    if (!statePath) return;
+    try {
+      const parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+      if (parsed && parsed.entries && typeof parsed.entries === "object") {
+        for (const [k, v] of Object.entries(parsed.entries)) {
+          if (v && v.start) {
+            const start = norm(v.start);
+            // current re-derives on the next send; seed it from start until then.
+            byKey.set(k, { start, current: { ...start } });
+          }
+        }
+      }
+    } catch (_e) {
+      // Missing/corrupt store is non-fatal: start empty.
+    }
+  }
+
+  function persist() {
+    if (!statePath) return;
+    try {
+      const entries = {};
+      for (const [k, v] of byKey.entries()) entries[k] = { start: v.start };
+      const tmp = `${statePath}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ version: 1, entries }), { mode: 0o600 });
+      fs.renameSync(tmp, statePath);
+    } catch (_e) {
+      // Best-effort persistence.
+    }
+  }
+
+  function evictIfNeeded() {
+    while (byKey.size > limit) {
+      const oldest = byKey.keys().next().value;
+      if (oldest === undefined) break;
+      byKey.delete(oldest);
+    }
+  }
+
+  load();
+
+  return {
+    record(sessionKey, states) {
+      const cur = norm(states);
+      const existing = byKey.get(sessionKey);
+      if (!existing) {
+        byKey.set(sessionKey, { start: cur, current: cur });
+        evictIfNeeded();
+        persist(); // a new frozen start-state was recorded
+        return;
+      }
+      existing.current = cur; // start stays frozen; no persist (start unchanged)
+    },
+    getStart(sessionKey) {
+      const e = byKey.get(sessionKey);
+      return e ? { ...e.start } : { ...DEFAULTS };
+    },
+    getCurrent(sessionKey) {
+      const e = byKey.get(sessionKey);
+      return e ? { ...e.current } : { ...DEFAULTS };
+    },
+    clear(sessionKey) {
+      if (byKey.delete(sessionKey)) persist();
+    },
+  };
+}
+
+export default createDisplayToggleTracker;

package/dist/runtime/glasses-backpressure-latch.js

@@ -0,0 +1,115 @@
+// Main-side latch over the worker's send-buffer high-water count (roadmap
+// step 4a). The worker transport counts app clients whose ws.bufferedAmount
+// exceeds the high-water mark every health heartbeat and posts the count to
+// main; this latch converts those reports into the boolean the glasses-ui
+// paint-floor shed consumes (relay-service.isGlassesSendBufferOverHighWater).
+//
+// LEAF MODULE: must not import other relay runtime modules (the CJS emitter
+// resolves bidirectional imports to {} mid-cycle — see
+// memory/ocuclaw-cjs-emitter-import-cycle).
+//
+// Semantics:
+// - latch on any report with sendBufferHighWaterClients >= 1
+// - hysteresis: a 0-report clears only after recoveredHoldMs has elapsed
+//   since the last >=1 report (pressure flaps at paint cadence otherwise)
+// - decay: with no fresh report inside staleMs the latch fails OPEN (false)
+//   — a dead or wedged worker must never freeze glasses paints forever
+// - a report from a new workerEpoch discards prior state (worker restart)
+// - false->true / true->false transitions emit debug events so the 4b
+//   hardware validation can observe the shed firing
+
+const DEFAULT_RECOVERED_HOLD_MS = 3_000;
+const DEFAULT_STALE_MS = 5_000;
+
+export function createGlassesBackpressureLatch(options = {}) {
+  const now = typeof options.now === "function" ? options.now : Date.now;
+  const recoveredHoldMs = Number.isFinite(options.recoveredHoldMs)
+    ? options.recoveredHoldMs
+    : DEFAULT_RECOVERED_HOLD_MS;
+  const staleMs = Number.isFinite(options.staleMs) ? options.staleMs : DEFAULT_STALE_MS;
+  const emitDebug = typeof options.emitDebug === "function" ? options.emitDebug : () => {};
+
+  let latched = false;
+  let latchedAtMs = null;
+  let lastOverAtMs = null;
+  let lastReportAtMs = null;
+  let workerEpoch = null;
+
+  function clearState() {
+    latched = false;
+    latchedAtMs = null;
+    lastOverAtMs = null;
+    lastReportAtMs = null;
+  }
+
+  function emitTransition(nextLatched, reason, atMs) {
+    if (nextLatched === latched) return;
+    if (nextLatched) {
+      latchedAtMs = atMs;
+      emitDebug("glasses_backpressure_latched", "warn", { reason });
+    } else {
+      emitDebug("glasses_backpressure_cleared", "info", {
+        reason,
+        latchedForMs: latchedAtMs === null ? null : Math.max(0, atMs - latchedAtMs),
+      });
+      latchedAtMs = null;
+    }
+    latched = nextLatched;
+  }
+
+  /** Re-evaluate decay/hysteresis clears against the clock. */
+  function evaluate(atMs) {
+    if (!latched) return;
+    if (lastReportAtMs !== null && atMs - lastReportAtMs > staleMs) {
+      emitTransition(false, "stale_reports", atMs);
+      return;
+    }
+    if (
+      lastOverAtMs !== null &&
+      atMs - lastOverAtMs >= recoveredHoldMs &&
+      lastReportAtMs !== null &&
+      lastReportAtMs > lastOverAtMs
+    ) {
+      // The newest report said 0 and the hold window since the last >=1
+      // report has fully elapsed.
+      emitTransition(false, "recovered", atMs);
+    }
+  }
+
+  function report(params) {
+    const atMs = now();
+    const count =
+      params && Number.isFinite(params.sendBufferHighWaterClients)
+        ? params.sendBufferHighWaterClients
+        : null;
+    if (count === null) return;
+    const epoch = params && Number.isFinite(params.workerEpoch) ? params.workerEpoch : null;
+    if (epoch !== null && workerEpoch !== null && epoch !== workerEpoch) {
+      // Worker restarted: prior pressure belongs to dead sockets.
+      clearState();
+    }
+    if (epoch !== null) workerEpoch = epoch;
+    lastReportAtMs = atMs;
+    if (count >= 1) {
+      lastOverAtMs = atMs;
+      emitTransition(true, "over_high_water", atMs);
+      return;
+    }
+    evaluate(atMs);
+  }
+
+  function isOverHighWater() {
+    evaluate(now());
+    return latched;
+  }
+
+  function reset(reason) {
+    const atMs = now();
+    emitTransition(false, typeof reason === "string" ? reason : "reset", atMs);
+    clearState();
+  }
+
+  return { report, isOverHighWater, reset };
+}
+
+export default { createGlassesBackpressureLatch };

package/dist/runtime/register-session-title-distiller.js

@@ -0,0 +1,100 @@
+import * as fs from "node:fs/promises";
+import { createSessionTitleDistiller } from "./session-title-distiller.js";
+import { stripAgentSessionPrefix } from "./session-title-distiller-helpers.js";
+
+function genRunId() {
+  const c = globalThis && globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return `ocuclaw-title-${c.randomUUID()}`;
+  return `ocuclaw-title-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+export function registerSessionTitleDistiller(api, service) {
+  if (!api || typeof api.on !== "function") return () => {};
+  // The budget lives in sessionService (so a logical reset clears it with the
+  // title record + toggle state). Resolve it lazily per call: at registration
+  // the live relay may not exist yet, and a sibling context resolves the shared
+  // relay's budget.
+  const budget = {
+    canRun: (k) => {
+      const b = service.getDistillerBudget();
+      return b ? b.canRun(k) : true;
+    },
+    recordTurn: (k) => {
+      const b = service.getDistillerBudget();
+      if (b) b.recordTurn(k);
+    },
+    recordOutcome: (k, o) => {
+      const b = service.getDistillerBudget();
+      if (b) b.recordOutcome(k, o);
+    },
+  };
+  const distiller = createSessionTitleDistiller({
+    // Lazy getter: the real state dir only arrives at service.start(), after
+    // this distiller is constructed during registration.
+    getStateDir: () => (service.getStateDir ? service.getStateDir() : undefined),
+    nowMs: () => Date.now(),
+    genId: genRunId,
+    emitDebug: (...a) => (service.emitDebug ? service.emitDebug(...a) : undefined),
+    getSessionTitleModel: () => service.getRuntimeConfig().sessionTitleModel || "",
+    conversationState: { getRawMessages: () => service.getRawMessages() },
+    sessionService: {
+      getSessionTitleRecord: (k) => service.getSessionTitleRecord(k),
+      isNeuralSessionNamesEnabled: (k) => service.isNeuralSessionNamesEnabled(k),
+      isSessionUserLocked: (k) => service.isSessionUserLocked(k),
+      hasRecordedUserMessage: (k) => service.hasRecordedUserMessage(k),
+      setSessionTitle: (k, t, o) => service.setSessionTitle(k, t, o),
+    },
+    isEvenAiSessionKey: (k) => service.isEvenAiSessionKey(k),
+    cleanupDistillerSession: (k) =>
+      typeof service.deleteDistillerSession === "function"
+        ? service.deleteDistillerSession(k)
+        : Promise.resolve(null),
+    subagentRuntime: (() => {
+      const sa = api && api.runtime && api.runtime.subagent;
+      if (
+        !sa ||
+        typeof sa.run !== "function" ||
+        typeof sa.waitForRun !== "function" ||
+        typeof sa.getSessionMessages !== "function" ||
+        typeof sa.deleteSession !== "function"
+      ) {
+        return null;
+      }
+      return {
+        run: (p) => sa.run(p),
+        waitForRun: (p) => sa.waitForRun(p),
+        getSessionMessages: (p) => sa.getSessionMessages(p),
+        deleteSession: (p) => sa.deleteSession(p),
+      };
+    })(),
+    gatewayBridge: {
+      request: (m, p, o) => service.gatewayRequest(m, p, o),
+      on: (evt, cb) => service.onGatewayEvent(evt, cb),
+    },
+    fs,
+    budget,
+  });
+
+  return api.on("agent_end", (event, ctx) => {
+    // 2026.6.x delivers the canonical `agent:<id>:<key>` form; relay state is
+    // keyed by the bare relay key — normalize at the boundary.
+    const rawSessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
+    const sessionKey = stripAgentSessionPrefix(rawSessionKey);
+    if (!sessionKey) return;
+    // Capture the completed run's messages NOW, before the fire-and-forget run
+    // defers: agent_end carries the run's final messages (the authoritative
+    // source for THIS session). Fall back to a synchronous snapshot of the live
+    // conversation state. Either way the messages are pinned here so a later
+    // session switch / clear can't make the distiller title from another
+    // session's transcript.
+    const eventMessages = event && Array.isArray(event.messages) ? event.messages : null;
+    const messages =
+      eventMessages && eventMessages.length
+        ? eventMessages
+        : service.getRawMessages();
+    // Fire-and-forget; never block run teardown.
+    Promise.resolve(distiller.maybeRun(sessionKey, { messages })).catch(() => {});
+  });
+}
+
+export default registerSessionTitleDistiller;