ocuclaw 1.3.2 → 1.3.3

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/relay-core.js

@@ -18,9 +18,11 @@ import { createEvenAiRunWaiter } from "../even-ai/even-ai-run-waiter.js";
 import { createEvenAiSettingsStore } from "../even-ai/even-ai-settings-store.js";
 import { createPluginOpenclawClient } from "../gateway/openclaw-client.js";
 import { createPluginRpcGatewayBridge } from "../gateway/gateway-bridge.js";
+import { createAgentTurnTracker } from "../tools/glasses-ui-wake.js";
 import { createDownstreamHandler } from "./downstream-handler.js";
 import { createOcuClawSettingsStore } from "./ocuclaw-settings-store.js";
 import { createRelayHealthMonitor } from "./relay-health-monitor.js";
+import { createGlassesBackpressureLatch } from "./glasses-backpressure-latch.js";
 import { createRelayOperationRegistry } from "./relay-operation-registry.js";
 import { createRelayWorkerSupervisor } from "./relay-worker-supervisor.js";
 import {
@@ -29,6 +31,9 @@ import {
 } from "./session-service.js";
 import { createUpstreamRuntime } from "./upstream-runtime.js";
 
+const GLASSES_UI_MARKERS = new Set(["listening", "parked", "inflight"]);
+export function sanitizeGlassesMarker(v) { return GLASSES_UI_MARKERS.has(v) ? v : undefined; }
+
 const SONIOX_TEMP_KEY_URL = "https://api.soniox.com/v1/auth/temporary-api-key";
 const SONIOX_MODELS_URL = "https://api.soniox.com/v1/models";
 const DEFAULT_SONIOX_TEMP_KEY_EXPIRES_IN_SECONDS = 3600;
@@ -342,6 +347,12 @@ function createRelay(opts) {
   const activityStatusAdapter = createActivityStatusAdapter(
     opts.activityStatusAdapter,
   );
+  // Per-session "agent turn in flight or imminent" signal (roadmap 6f):
+  // marked busy on every dispatched send (voice/user/wake), refreshed by the
+  // gateway activity stream, idled on end-phase activity, decay-bounded
+  // (fail open). The glasses-ui wake controller consults it so a wake never
+  // races a genuine turn (voice absorbs wake, §2.6c).
+  const agentTurnTracker = createAgentTurnTracker();
   const sharedHttpServer = opts.httpServer || null;
 
   // --- Cached state ---
@@ -1262,6 +1273,10 @@ function createRelay(opts) {
     const runId = activity && activity.runId ? activity.runId : null;
     const origin = activity && activity.origin ? activity.origin : null;
     const phase = activity && activity.phase ? activity.phase : null;
+    agentTurnTracker.onActivity(
+      (activity && activity.sessionKey) || sessionService.ensureSessionKey(),
+      phase,
+    );
 
     emitDebug(
       "app.timeline",
@@ -1348,6 +1363,7 @@ function createRelay(opts) {
       surfaceId: params && typeof params.surfaceId === "string" ? params.surfaceId : "",
       depth: Number.isFinite(params && params.depth) ? Math.floor(params.depth) : 1,
       spec: params && params.spec ? params.spec : null,
+      marker: sanitizeGlassesMarker(params && params.marker),
     };
     server.broadcast(JSON.stringify(payload));
     emitDebug(
@@ -1382,6 +1398,7 @@ function createRelay(opts) {
         })
         .filter((i) => i !== null);
     }
+    const m = sanitizeGlassesMarker(patch.marker); if (m) cleanPatch.marker = m;
     const payload = {
       type: "glasses_ui_surface_update",
       sessionKey: params && typeof params.sessionKey === "string" ? params.sessionKey : null,
@@ -1542,6 +1559,9 @@ function createRelay(opts) {
     );
 
     return maybeSeedOcuClawSessionConfig(resolvedSessionKey).then(() => {
+      // A genuine user/voice send is starting an agent turn — mark the
+      // session busy so a racing glasses wake is absorbed (§2.6c).
+      agentTurnTracker.markBusy(resolvedSessionKey);
       // Dispatch upstream first so local transcript work cannot delay first
       // model tokens on large histories.
       const upstreamPromise = gatewayBridge.sendMessage(
@@ -2676,6 +2696,14 @@ function createRelay(opts) {
 
   const pluginVersionService = createPluginVersionService();
 
+  // Roadmap 4a: latch the worker's per-heartbeat send-buffer pressure counts
+  // into the boolean the glasses-ui paint-floor shed queries
+  // (isGlassesSendBufferOverHighWater on the relay API / relay-service facade).
+  const glassesBackpressureLatch = createGlassesBackpressureLatch({
+    emitDebug: (event, severity, data) =>
+      emitDebug("relay.health", event, severity, null, () => data || {}),
+  });
+
   server = createRelayWorkerSupervisor({
     pluginId: "ocuclaw",
     getPluginVersion: () => pluginVersionService.getPluginVersion(),
@@ -2686,6 +2714,7 @@ function createRelay(opts) {
     host: opts.host,
     port: opts.port,
     token: opts.token,
+    onWorkerBackpressure: (message) => glassesBackpressureLatch.report(message),
     externalDebugToolsEnabled,
     evenAiRequestTimeoutMs: opts.evenAiRequestTimeoutMs,
     evenAiMaxBodyBytes: opts.evenAiMaxBodyBytes,
@@ -3331,6 +3360,48 @@ function createRelay(opts) {
       sendGlassesUiSurfaceUpdate(params);
     },
 
+    /**
+     * Tap-to-wake lane (roadmap 6f): ONE agent turn for a parked glasses
+     * gesture, dispatched through the same gateway client the voice send
+     * uses. The MESSAGE is built (and sanitized) by the glasses-ui wake
+     * controller — refs-only with non-wearer provenance framing; this method
+     * is a dumb transport and deliberately does NOT touch the local
+     * conversation state (a wake is not a wearer utterance — no synthetic
+     * user message without provenance, §2.6).
+     */
+    dispatchGlassesWake(params) {
+      const sessionKey =
+        params && typeof params.sessionKey === "string" && params.sessionKey
+          ? params.sessionKey
+          : sessionService.ensureSessionKey();
+      const message = params && typeof params.message === "string" ? params.message : "";
+      if (!message) {
+        return Promise.reject(new Error("dispatchGlassesWake requires a message"));
+      }
+      const idempotencyKey =
+        params && typeof params.idempotencyKey === "string" && params.idempotencyKey
+          ? params.idempotencyKey
+          : null;
+      agentTurnTracker.markBusy(sessionKey);
+      emitDebug(
+        "relay.protocol",
+        "glasses_wake_dispatch",
+        "info",
+        { sessionKey },
+        () => ({
+          idempotencyKey,
+          messageChars: message.length,
+        }),
+      );
+      const requestParams = { message, sessionKey };
+      if (idempotencyKey) requestParams.idempotencyKey = idempotencyKey;
+      return gatewayBridge.request("agent", requestParams, { expectFinal: false });
+    },
+
+    isAgentTurnBusy(sessionKey) {
+      return agentTurnTracker.isBusy(sessionKey);
+    },
+
     onGlassesUiResult(handler) {
       return onGlassesUiResult(handler);
     },
@@ -3351,6 +3422,10 @@ function createRelay(opts) {
       return server ? server.getConnectedAppCount() > 0 : false;
     },
 
+    isGlassesSendBufferOverHighWater() {
+      return glassesBackpressureLatch.isOverHighWater();
+    },
+
     onAppClientDisconnect(handler) {
       return onAppClientDisconnect(handler);
     },

package/dist/runtime/relay-service.js

@@ -447,6 +447,38 @@ export function createOcuClawRelayService(opts = {}) {
       }
       return false;
     },
+    isGlassesSendBufferOverHighWater() {
+      // Roadmap 4a: glasses-ui paint-floor shed signal (glasses-ui-tool.ts
+      // already consults this; false = no shedding, the safe default).
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isGlassesSendBufferOverHighWater === "function") {
+        return liveRelay.isGlassesSendBufferOverHighWater();
+      }
+      return false;
+    },
+    // Tap-to-wake lane + busy signal (roadmap 6f). registerGlassesUiTool
+    // probes these at plugin register() time — BEFORE start() — and wires
+    // dispatchWake to null when the probe fails, so they must exist on the
+    // facade unconditionally and resolve the live (possibly shared) relay at
+    // call time, like every other passthrough above.
+    dispatchGlassesWake(params) {
+      const liveRelay = resolveLiveRelay();
+      if (!liveRelay || typeof liveRelay.dispatchGlassesWake !== "function") {
+        // The wake controller retries once, then parks the wake in its
+        // durable outbox with a warn lifecycle — never silent after the ✓-ack.
+        return Promise.reject(new Error("ocuclaw relay not started"));
+      }
+      return liveRelay.dispatchGlassesWake(params);
+    },
+    isAgentTurnBusy(sessionKey) {
+      const liveRelay = resolveLiveRelay();
+      if (liveRelay && typeof liveRelay.isAgentTurnBusy === "function") {
+        return liveRelay.isAgentTurnBusy(sessionKey);
+      }
+      // Idle, not busy: a missing relay must surface through the dispatch
+      // path's failure handling, never suppress wakes as phantom-busy.
+      return false;
+    },
     start,
     stop,
   };

package/dist/runtime/relay-worker-supervisor.js

@@ -777,6 +777,14 @@ export function createRelayWorkerSupervisor(options = {}) {
       postMainFrame("unicast", frame, pending.requesterClientId);
       return;
     }
+    if (message.kind === "worker.backpressure") {
+      // Roadmap 4a: heartbeat-cadence send-buffer pressure counts from the
+      // worker transport; relay-core latches them for the glasses paint shed.
+      if (typeof options.onWorkerBackpressure === "function") {
+        options.onWorkerBackpressure(message);
+      }
+      return;
+    }
     if (message.kind === "debug" && typeof options.emitDebug === "function") {
       options.emitDebug(
         message.category || "relay.worker.health",

package/dist/runtime/relay-worker-transport.js

@@ -997,8 +997,17 @@ export function createRelayWorkerTransport(options = {}) {
     }, Math.max(10, Math.min(1000, manifest.queue.messageSendTtlMs)));
     healthTimer = setInterval(() => {
       health.updateLoopLagP95Ms(sampleLoopLagP95Ms());
-      health.updateSendBufferHighWaterClients(countSendBufferHighWaterClients());
+      const sendBufferHighWaterClients = countSendBufferHighWaterClients();
+      health.updateSendBufferHighWaterClients(sendBufferHighWaterClients);
       health.sample();
+      // Roadmap 4a: main holds the glasses paint-floor shed latch; the ws
+      // sockets (and their bufferedAmount) live here in the worker, so the
+      // count crosses on every heartbeat (the latch fail-opens on staleness).
+      postToMain({
+        kind: "worker.backpressure",
+        workerEpoch: manifest.workerEpoch,
+        sendBufferHighWaterClients,
+      });
     }, manifest.health.heartbeatIntervalMs);
     postToMain({ kind: "worker.ready", workerEpoch: manifest.workerEpoch, address: address() });
   }

package/dist/tools/glasses-ui-cron.js

@@ -311,6 +311,12 @@ export function createGlassesUiCronEngine(deps) {
         resolved: false,
         nextTickTimer: null,
         maxDurationTimer: null,
+        // Pause-aware duration accounting (roadmap 6e): the cap measures
+        // ACTIVE time only. remainingMs is banked on pause and re-armed on
+        // resume; armedAtMs is monotonic (never wall-clock — the 2026-06-01
+        // freeze came from mixing clocks).
+        maxDurationRemainingMs: params.refresh.maxDurationMs,
+        maxDurationArmedAtMs: null,
         isSmokeTest: false,
         lastTickAt: null,
         generationToken: 0,
@@ -319,7 +325,14 @@ export function createGlassesUiCronEngine(deps) {
       };
       active.set(state.surfaceId, state);
       // Arm the duration cap.
+      state.maxDurationArmedAtMs = monotonicNowMs();
       state.maxDurationTimer = setTimeoutFn(() => {
+        // Cron-death observability (Wave-1 e2e leg-4 gap): the cap firing was
+        // invisible — bounded tick-silence watches were the only evidence.
+        emitLifecycle("cron_max_duration_reached", "debug", {
+          surfaceId: state.surfaceId,
+          sessionKey: state.sessionKey,
+        });
         resolveAndClean(state, { result: "timeout" });
       }, params.refresh.maxDurationMs);
       // start() is sync; runSmokeTest is async. Catch any rejection so it
@@ -380,6 +393,20 @@ export function createGlassesUiCronEngine(deps) {
         clearTimeoutFn(state.nextTickTimer);
         state.nextTickTimer = null;
       }
+      // Pause-aware duration cap (roadmap 6e): stop the wall-clock burn and
+      // bank the remaining ACTIVE budget. Pre-6e the cap kept running while
+      // the parent hid under a pushed child — hardware-observed 2026-06-11
+      // as cron_resume {found:false} → Back landed on a frozen list. Guarded
+      // on the timer handle so a double-pause cannot double-deduct.
+      if (state.maxDurationTimer) {
+        clearTimeoutFn(state.maxDurationTimer);
+        state.maxDurationTimer = null;
+        state.maxDurationRemainingMs = Math.max(
+          0,
+          state.maxDurationRemainingMs - (monotonicNowMs() - state.maxDurationArmedAtMs),
+        );
+        state.maxDurationArmedAtMs = null;
+      }
       state.paused = true;
       // Bump so an in-flight tick (started before pause) is discarded when it
       // resolves — it must not patch the now-hidden parent screen.
@@ -398,6 +425,29 @@ export function createGlassesUiCronEngine(deps) {
         });
         return false;
       }
+      // Re-arm the duration cap with the banked ACTIVE remainder (roadmap
+      // 6e). An exhausted budget resolves terminal timeout here instead of
+      // re-arming a dead cron — honest death beats a zombie surface.
+      if (!state.maxDurationTimer) {
+        if (state.maxDurationRemainingMs <= 0) {
+          emitLifecycle("cron_resume", "debug", {
+            surfaceId,
+            found: true,
+            resolved: false,
+            branch: "max_duration_exhausted",
+          });
+          resolveAndClean(state, { result: "timeout" });
+          return false;
+        }
+        state.maxDurationArmedAtMs = monotonicNowMs();
+        state.maxDurationTimer = setTimeoutFn(() => {
+          emitLifecycle("cron_max_duration_reached", "debug", {
+            surfaceId: state.surfaceId,
+            sessionKey: state.sessionKey,
+          });
+          resolveAndClean(state, { result: "timeout" });
+        }, state.maxDurationRemainingMs);
+      }
       state.paused = false;
       if (state.nextTickTimer) {
         clearTimeoutFn(state.nextTickTimer);

package/dist/tools/glasses-ui-paint-floor.js

@@ -35,6 +35,14 @@ export function createPaintFloorCoalescer(deps) {
     return !!(p && p.__render === true);
   }
 
+  function markerOf(p) {
+    if (!p) return undefined;
+    return p.__marker !== undefined ? p.__marker : p.marker;
+  }
+  function isMarkerOnly(p) {
+    return !!p && !isRenderSentinel(p) && Object.keys(p).length === 1 && p.marker !== undefined;
+  }
+
   function mergePatch(base, incoming) {
     // A render sentinel ({ __render, __depth, __spec }, Task 13) and a field
     // patch ({ body }/{ items }/{ title }) must NEVER shallow-merge — a merged
@@ -43,8 +51,22 @@ export function createPaintFloorCoalescer(deps) {
     // earlier one wholesale (a render replaces a queued field patch; a field
     // patch after a queued render replaces that render). Same-kind writes
     // merge last-write-wins per field as before.
+    //
+    // Marker-only field patch must NEVER drop a queued render (7a): merge the
+    // marker onto the render sentinel instead of superseding it wholesale.
+    if (isMarkerOnly(incoming) && isRenderSentinel(base)) {
+      return { ...base, __marker: incoming.marker };
+    }
     if (isRenderSentinel(base) !== isRenderSentinel(incoming)) {
-      return incoming && typeof incoming === "object" ? { ...incoming } : {};
+      // Different write kinds: later supersedes wholesale (a render replaces a
+      // queued field patch; a content field patch replaces a queued render).
+      // Marker is sticky — carry it forward if the survivor didn't set one.
+      const next = incoming && typeof incoming === "object" ? { ...incoming } : {};
+      if (markerOf(next) === undefined) {
+        const m = markerOf(base);
+        if (m !== undefined) { if (isRenderSentinel(next)) next.__marker = m; else next.marker = m; }
+      }
+      return next;
     }
     const merged = base ? { ...base } : {};
     if (incoming && typeof incoming === "object") {