ocuclaw 1.3.1 → 1.3.3

package/dist/runtime/relay-core.js

@@ -9,6 +9,8 @@ import { composeReadabilitySystemPrompt } from "../domain/readability-system-pro
 import { composeNeuralEmojiReactorSystemPrompt } from "../domain/neural-emoji-reactor-system-prompt.js";
 import { composeNeuralPaceModulatorSystemPrompt } from "../domain/neural-pace-modulator-system-prompt.js";
 import { composeGlassesUiNudgeSystemPrompt } from "../domain/glasses-ui-system-prompt.js";
+import { composeGlassesDisplaySystemPrompt } from "../domain/glasses-display-system-prompt.js";
+import { createStablePromptSnapshotStore } from "./stable-prompt-snapshot.js";
 import { createActivityStatusAdapter } from "../domain/activity-status-adapter.js";
 import { createEvenAiEndpoint } from "../even-ai/even-ai-endpoint.js";
 import { createEvenAiRouter } from "../even-ai/even-ai-router.js";
@@ -16,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 {
@@ -27,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;
@@ -340,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 ---
@@ -359,7 +372,9 @@ function createRelay(opts) {
   /** Relay-local deterministic simulate-stream run sequence counter. */
   let simulateStreamRunSeq = 0;
   /** Active timers for relay-local deterministic simulate-stream runs. */
-  const simulateStreamTimers = new Set();
+  // timer -> sessionKey, so new-chat//reset/new-session can cancel ONLY the
+  // affected session's pending injections (re-land of a8a29032, session-scoped).
+  const simulateStreamTimers = new Map();
 
   // --- Structured debug state ---
 
@@ -550,7 +565,7 @@ function createRelay(opts) {
     );
   }
 
-  function scheduleSimulateStreamTimer(delayMs, callback) {
+  function scheduleSimulateStreamTimer(delayMs, callback, sessionKey) {
     const timer = setTimeout(() => {
       simulateStreamTimers.delete(timer);
       try {
@@ -559,12 +574,29 @@ function createRelay(opts) {
         logger.error(`[relay] simulate-stream timer failed: ${err.message}`);
       }
     }, delayMs);
-    simulateStreamTimers.add(timer);
+    simulateStreamTimers.set(timer, typeof sessionKey === "string" ? sessionKey : null);
     return timer;
   }
 
+  function clearSimulateStreamTimersForSession(sessionKey) {
+    let cleared = 0;
+    for (const [timer, timerSessionKey] of simulateStreamTimers) {
+      if (timerSessionKey === sessionKey) {
+        clearTimeout(timer);
+        simulateStreamTimers.delete(timer);
+        cleared += 1;
+      }
+    }
+    if (cleared > 0) {
+      logger.info(
+        `[relay] cancelled ${cleared} pending simulate-stream timer(s) for session ${sessionKey}`,
+      );
+    }
+    return cleared;
+  }
+
   function clearSimulateStreamTimers() {
-    for (const timer of simulateStreamTimers) {
+    for (const timer of simulateStreamTimers.keys()) {
       clearTimeout(timer);
     }
     simulateStreamTimers.clear();
@@ -923,37 +955,67 @@ function createRelay(opts) {
       systemPrompt: opts.ocuClawSystemPrompt,
     },
   });
-
-  function currentOcuClawSendOptions(perTurnSignals) {
-    const signals = perTurnSignals || {};
+  const stablePromptSnapshots = createStablePromptSnapshotStore({
+    stateDir: opts.stateDir,
+    emitDebug,
+  });
+  // Hourly TTL sweep for stale stable-prompt snapshots; started in start(),
+  // cleared in stop(). Declared here so both can see it.
+  let stablePromptSweepTimer = null;
+
+  // Channel 1: the per-session-immutable extraSystemPrompt. Computed once from
+  // the feature set AT SESSION START and then served byte-identical for the
+  // session's lifetime (see stable-prompt-snapshot). Mid-session toggles are
+  // bridged by the Channel-2 hook composer, NOT here. The glasses-UI pointer is
+  // always present (its disconnected gate moved to Channel 2); the emoji/pace
+  // blocks are included only when active at session start.
+  function computeStableChannelOne(startSignals) {
     const baseReadability = composeReadabilitySystemPrompt(
       ocuClawSettingsStore.getSnapshot().systemPrompt,
     );
-    const validState = (raw) =>
-      raw === "active" || raw === "recently-disabled" || raw === "inactive"
-        ? raw
-        : "inactive";
-    const reactorState = validState(signals.neuralEmojiReactorState);
-    const paceState = validState(signals.neuralPaceModulatorState);
-    const reactor = composeNeuralEmojiReactorSystemPrompt({ state: reactorState });
-    const pace = composeNeuralPaceModulatorSystemPrompt({ state: paceState });
-    // Only include the glasses-UI nudge when a downstream app client is
-    // connected. Keeps the prompt clean when the agent has nowhere to render
-    // the tool's output, and keeps existing prompt-assembly tests stable
-    // (they exercise the prompt without spinning up an app client).
-    const hasAppClient =
-      server &&
-      typeof server.getConnectedAppCount === "function" &&
-      server.getConnectedAppCount() > 0;
-    const glassesUiNudge = hasAppClient ? composeGlassesUiNudgeSystemPrompt() : "";
+    const display = composeGlassesDisplaySystemPrompt({
+      emoji: startSignals.emoji,
+      pace: startSignals.pace,
+    });
+    const glassesPointer = composeGlassesUiNudgeSystemPrompt();
     const parts = [];
     if (baseReadability) parts.push(baseReadability);
-    if (reactor) parts.push(reactor);
-    if (pace) parts.push(pace);
-    if (glassesUiNudge) parts.push(glassesUiNudge);
-    return {
-      extraSystemPrompt: parts.join("\n\n"),
-    };
+    if (display) parts.push(display);
+    if (glassesPointer) parts.push(glassesPointer);
+    return parts.join("\n\n");
+  }
+
+  function stableSendOptions(resolvedSessionKey, sessionId, perTurnSignals) {
+    const signals = perTurnSignals || {};
+    // "enabled at start" = the client's reported state on the FIRST send of the
+    // session. The 3-state client signal maps to a boolean: only "active" counts.
+    const startEmoji = signals.neuralEmojiReactorState === "active";
+    const startPace = signals.neuralPaceModulatorState === "active";
+    const extraSystemPrompt = stablePromptSnapshots.getOrCreate(
+      resolvedSessionKey,
+      sessionId,
+      () => computeStableChannelOne({ emoji: startEmoji, pace: startPace }),
+    );
+    // Churn guard: if recomputing TODAY would differ from the served snapshot,
+    // something is mutating Channel 1 mid-session (e.g. a toggle flipped the
+    // start-state signals) — the case that used to reset the CLI session.
+    // Surface it loudly; the served prompt stays the frozen snapshot.
+    if (
+      stablePromptSnapshots.wouldChurn(
+        resolvedSessionKey,
+        sessionId,
+        computeStableChannelOne({ emoji: startEmoji, pace: startPace }),
+      )
+    ) {
+      emitDebug(
+        "relay.session",
+        "stable_prompt_churn_detected",
+        "warn",
+        { sessionKey: resolvedSessionKey },
+        () => ({ sessionId: sessionId || null }),
+      );
+    }
+    return { extraSystemPrompt };
   }
 
   function buildOcuClawSendDiagnostic(params = {}) {
@@ -1211,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",
@@ -1297,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(
@@ -1331,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,
@@ -1465,6 +1533,10 @@ function createRelay(opts) {
         resolvedSessionKey,
         clientDisplaySignals.neuralSessionNamesEnabled !== false,
       );
+      sessionService.recordDisplayToggleStates(resolvedSessionKey, {
+        emoji: clientDisplaySignals.neuralEmojiReactorState === "active",
+        pace: clientDisplaySignals.neuralPaceModulatorState === "active",
+      });
     }
     const hasAttachment = !!attachment;
     const sendStartedAt = Date.now();
@@ -1487,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(
@@ -1494,7 +1569,16 @@ function createRelay(opts) {
         resolvedSessionKey,
         attachment,
         {
-          ...currentOcuClawSendOptions(clientDisplaySignals),
+          ...stableSendOptions(
+            resolvedSessionKey,
+            // No synchronous OpenClaw sessionId is available at send time
+            // (resolveSessionCanonicalKey is async). Use the sessionKey as the
+            // snapshot's id; the sessionId-mismatch guard is therefore a no-op,
+            // and new-session safety rests on logical-session-end eviction
+            // (onNewSession / onNewChat / onDeleteSessions evict the snapshot).
+            resolvedSessionKey,
+            clientDisplaySignals,
+          ),
           diagnostic: buildOcuClawSendDiagnostic({
             ...params,
             sessionKey: resolvedSessionKey,
@@ -1768,6 +1852,14 @@ function createRelay(opts) {
       return upstreamRuntime.compactActiveSession(sessionKey);
     },
     onDeleteSessions(sessionKeys, kind, switchBeforeDelete) {
+      if (Array.isArray(sessionKeys)) {
+        for (const key of sessionKeys) {
+          if (typeof key === "string" && key.trim()) {
+            stablePromptSnapshots.evict(key);
+            sessionService.clearDisplayToggleStates(key);
+          }
+        }
+      }
       const action = switchBeforeDelete
         ? sessionService.switchAndDeleteSessions(kind, sessionKeys)
         : sessionService.deleteSessions(kind, sessionKeys);
@@ -1904,7 +1996,7 @@ function createRelay(opts) {
               totalChars: text.length,
             }),
           );
-        });
+        }, sessionKey);
       }
 
       const completeDelayMs = startDelayMs + (chunkCount * chunkIntervalMs) + thinkingTailMs;
@@ -1935,7 +2027,7 @@ function createRelay(opts) {
             completeDelayMs,
           }),
         );
-      });
+      }, sessionKey);
 
       return Promise.resolve({
         status: "accepted",
@@ -1962,7 +2054,18 @@ function createRelay(opts) {
       }
       sessionService.invalidateSessionsCache();
       resetActivityStatusAdapter();
+      // Cancel THIS session's pending simulate-stream timers BEFORE clearing —
+      // a deferred addMessage firing after the clear repopulates the fresh chat
+      // (the 2026-05-15 canary-pollution mechanism).
+      clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       conversationState.clear();
+      // Logical session end: this key is REUSED for a fresh conversation, so the
+      // Channel-1 snapshot must be dropped or the next send serves a stale prompt,
+      // and ALL other per-session state keyed to it (title + upstream name,
+      // toggles, distiller budget, first-user marker) must be cleared too.
+      const newChatSessionKey = sessionService.ensureSessionKey();
+      stablePromptSnapshots.evict(newChatSessionKey);
+      sessionService.clearLogicalSessionState(newChatSessionKey);
       conversationState.setAgentName(
         (upstreamRuntime ? upstreamRuntime.getAgentName() : null) || "Agent",
       );
@@ -2000,7 +2103,20 @@ function createRelay(opts) {
     },
 
     async onNewSession() {
+      // Cancel pending simulate-stream timers scheduled under the outgoing key
+      // BEFORE the new key is minted — a deferred addMessage firing after the
+      // switch would repopulate the fresh session's shared conversation view.
+      clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
       const result = await sessionService.newSession();
+      // newSession() mints a FRESH key; defensively clear only the NEW key (it
+      // has no snapshot yet). Do NOT touch the previous key: that session stays
+      // resumable via onSwitchSession, and dropping its frozen snapshot would
+      // recompute — and churn — Channel 1 if the user switches back to it. The
+      // previous session's snapshot is released by delete or the TTL sweep.
+      if (result && typeof result.sessionKey === "string" && result.sessionKey.trim()) {
+        stablePromptSnapshots.evict(result.sessionKey);
+        sessionService.clearDisplayToggleStates(result.sessionKey);
+      }
       clearCurrentSessionModelConfigSnapshot("new_session");
       if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
         upstreamRuntime.clearTyping("new_session");
@@ -2110,6 +2226,7 @@ function createRelay(opts) {
       if (command === "/reset") {
         sessionService.invalidateSessionsCache();
         resetActivityStatusAdapter();
+        clearSimulateStreamTimersForSession(sessionService.ensureSessionKey());
         conversationState.clear();
         if (upstreamRuntime && typeof upstreamRuntime.clearTyping === "function") {
           upstreamRuntime.clearTyping("slash_reset");
@@ -2119,6 +2236,19 @@ function createRelay(opts) {
         );
         broadcastPages();
       }
+      // A user-typed /new or /reset is a logical session reset on the CURRENT
+      // key (distinct from an automatic CLI session reset, which keeps the same
+      // logical session and must survive). Drop the frozen Channel-1 snapshot so
+      // the next real message recomputes it for the fresh conversation; otherwise
+      // the old conversation's prompt + display start-state bleed into the new one.
+      if (command === "/new" || command === "/reset") {
+        const resetKey = sessionService.ensureSessionKey();
+        stablePromptSnapshots.evict(resetKey);
+        // Clear ALL per-session state keyed to the reused key (title + upstream
+        // name, toggles, distiller budget, first-user marker) so nothing from the
+        // old conversation bleeds into the fresh one.
+        sessionService.clearLogicalSessionState(resetKey);
+      }
       if (upstreamRuntime && upstreamRuntime.isConnected()) {
         // Bare /reset no longer elicits an agent turn on OpenClaw 2026.6.x
         // (fast-reset). Append the greeting prompt so Reset gets the same
@@ -2566,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(),
@@ -2576,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,
@@ -3013,6 +3152,16 @@ function createRelay(opts) {
      * The downstream server is already listening from construction.
     */
     start() {
+      // Bounded cleanup of stale stable-prompt snapshots (14-day TTL).
+      if (!stablePromptSweepTimer) {
+        stablePromptSweepTimer = setInterval(
+          () => stablePromptSnapshots.sweep(),
+          60 * 60 * 1000, // hourly
+        );
+        if (typeof stablePromptSweepTimer.unref === "function") {
+          stablePromptSweepTimer.unref();
+        }
+      }
       const startGateway = () => Promise.resolve(gatewayBridge.start()).then(() => {
         prefetchSonioxModels("relay_start").catch((err) => {
           logger.warn(`[relay] Soniox models prefetch failed: ${err.message}`);
@@ -3034,6 +3183,10 @@ function createRelay(opts) {
      */
     stop() {
       clearSimulateStreamTimers();
+      if (stablePromptSweepTimer) {
+        clearInterval(stablePromptSweepTimer);
+        stablePromptSweepTimer = null;
+      }
       if (evenAiEndpoint) {
         evenAiEndpoint.close();
       }
@@ -3113,6 +3266,49 @@ function createRelay(opts) {
       return sessionService.isSessionUserLocked(sessionKey);
     },
 
+    getDisplayStartStates(sessionKey) {
+      return sessionService.getDisplayStartStates(sessionKey);
+    },
+
+    getDisplayCurrentStates(sessionKey) {
+      return sessionService.getDisplayCurrentStates(sessionKey);
+    },
+
+    // Accessors used by the session-title distiller sidecar.
+    getSessionTitleRecord(sessionKey) {
+      return sessionService.getSessionTitleRecord(sessionKey);
+    },
+    isEvenAiSessionKey(sessionKey) {
+      return sessionService.isEvenAiSessionKey(sessionKey);
+    },
+    getRawMessages() {
+      return conversationState.getRawMessages();
+    },
+    getDistillerBudget() {
+      return sessionService.getDistillerBudget();
+    },
+    // Canonical-key cleanup for the distiller's throwaway upstream session.
+    // The native subagent deleteSession passes the bare key straight to
+    // sessions.delete, which the 2026.6.x gateway indexes under the canonical
+    // agent:<id>: form — the bare-key delete silently no-ops and the
+    // excerpt-bearing transcript survives. deleteSessions() resolves the
+    // canonical key via sessions.resolve first.
+    deleteDistillerSession(sessionKey) {
+      return sessionService.deleteSessions("ocuclaw", [sessionKey]);
+    },
+    getStateDir() {
+      return opts.stateDir;
+    },
+    emitDebug(...args) {
+      return emitDebug(...args);
+    },
+    gatewayRequest(method, params, requestOpts) {
+      return gatewayBridge.request(method, params, requestOpts);
+    },
+    onGatewayEvent(eventName, listener) {
+      return gatewayBridge.on(eventName, listener);
+    },
+
     peekSessionKey() {
       return sessionService.peekSessionKey();
     },
@@ -3147,6 +3343,15 @@ function createRelay(opts) {
       return dispatchOcuClawUserSend(params || {});
     },
 
+    /**
+     * Test-only: run the logical-reset state clear (the same call the /new,
+     * /reset, and new-chat paths make) so integration tests can verify all
+     * per-session state is dropped for a reused session key.
+     */
+    _clearLogicalSessionState(sessionKey) {
+      sessionService.clearLogicalSessionState(sessionKey);
+    },
+
     sendGlassesUiRender(params) {
       sendGlassesUiRender(params);
     },
@@ -3155,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);
     },
@@ -3175,6 +3422,10 @@ function createRelay(opts) {
       return server ? server.getConnectedAppCount() > 0 : false;
     },
 
+    isGlassesSendBufferOverHighWater() {
+      return glassesBackpressureLatch.isOverHighWater();
+    },
+
     onAppClientDisconnect(handler) {
       return onAppClientDisconnect(handler);
     },