ocuclaw 1.3.1 → 1.3.3

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

@@ -0,0 +1,299 @@
+// Voicemail delivery for parked glasses events (roadmap 7b, §2.6 W+P+L).
+//
+// A parked, ✓-acked event whose wake could not run (no dispatch lane, or the
+// dispatch failed past its retry — the 6f wake outbox) or whose surface was
+// destructively reaped (the 6a per-session dead-letter) must not wait in
+// silence for the wearer to speak first. This module drains both sources into
+// a refs-only system-context fragment for the session's NEXT genuine turn —
+// the before_prompt_build hook registered by registerGlassesUiTool calls
+// buildInjection(sessionKey) and returns {appendSystemContext} (Channel-2
+// class: hash-exempt, per-turn).
+//
+// Locked rules carried over from the 6f security review (§2.6 amendments):
+// - REFS ONLY: surfaceUuid is pattern-validated against the plugin-mint shape
+//   and REPLACED WHOLESALE when off-pattern; result is enum-allowlisted; ints
+//   are Number.isFinite-coerced. Outcome/label text (selected_text etc.)
+//   NEVER reaches the prompt — tapped content arrives only through a surface
+//   collect, as tool-result data.
+// - Explicit non-wearer provenance header.
+// - Idempotency: an entry injects at most once (keyed on the wake
+//   idempotencyKey / a minted voicemail key), so re-entering entries and
+//   double-firing hooks cannot duplicate a delivery.
+// - TTL: stale voicemail drops LOUDLY (voicemail_expired lifecycle), never
+//   silently; dead-letter staleAfterMs (6b) additionally flags entries the
+//   agent should re-confirm before acting on.
+//
+// Leaf module (CJS emitter constraint): all state injected, no runtime deps.
+
+import { sanitizeWakeToken } from "./glasses-ui-wake.js";
+import { normalizeGlassesSessionKey } from "./glasses-ui-surfaces.js";
+
+export const DEFAULT_VOICEMAIL_TTL_MS = 30 * 60_000;
+export const VOICEMAIL_MAX_ENTRIES_PER_INJECTION = 8;
+// Bound on a session's buffered (not-yet-prompting) entries — a rotated or
+// disconnected session that never speaks again must not grow memory forever
+// (review P3). Newest kept, eviction is loud.
+export const VOICEMAIL_PENDING_CAP_PER_SESSION = 32;
+const DELIVERED_KEY_CAP = 256;
+
+const RESULT_ENUM = new Set(["selected", "back"]);
+// Store reap reasons (glasses-ui-surfaces deadLetterEntryEvents call sites).
+const REAP_REASON_ENUM = new Set(["drain_session", "drain_all", "exit", "pop_back"]);
+
+function coerceInt(value) {
+  return Number.isFinite(value) ? Math.floor(value) : null;
+}
+
+function sanitizeResult(value) {
+  return RESULT_ENUM.has(value) ? value : "event";
+}
+
+// idempotencyKey reaches the prompt verbatim-ish; constrain to the same safe
+// charset family as the minted forms and replace wholesale when off-pattern.
+const IDEMPOTENCY_KEY_PATTERN = /^[a-z0-9:._-]{1,80}$/i;
+function sanitizeIdempotencyKey(value) {
+  const raw = String(value == null ? "" : value);
+  return IDEMPOTENCY_KEY_PATTERN.test(raw) ? raw : "invalid";
+}
+
+export function createGlassesVoicemail(deps = {}) {
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const ttlMs = Number.isFinite(deps.ttlMs) ? deps.ttlMs : DEFAULT_VOICEMAIL_TTL_MS;
+  const maxEntries = Number.isFinite(deps.maxEntriesPerInjection)
+    ? deps.maxEntriesPerInjection
+    : VOICEMAIL_MAX_ENTRIES_PER_INJECTION;
+  const drainWakeOutbox =
+    typeof deps.drainWakeOutbox === "function" ? deps.drainWakeOutbox : () => [];
+  const drainDeadLetter =
+    typeof deps.drainDeadLetter === "function" ? deps.drainDeadLetter : () => [];
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+
+  // Outbox entries arrive for ALL sessions on each drain; buffer the
+  // non-target sessions' entries here so one session's prompt build never
+  // destroys another session's owed voicemail. Bounded per session and
+  // TTL-checked AT INGESTION (review P3) — buckets for silent sessions
+  // cannot grow without bound, and empty buckets are deleted.
+  const pendingBySession = new Map(); // normalized sessionKey -> [entry]
+  // Injected-once guard (bounded FIFO), keyed on the CANONICAL per-event key
+  // (surfaceUuid:eventId) so the same parked tap arriving via BOTH the wake
+  // outbox and the dead-letter injects exactly once (review P2).
+  const deliveredKeys = new Set();
+
+  function rememberDelivered(key) {
+    deliveredKeys.add(key);
+    if (deliveredKeys.size > DELIVERED_KEY_CAP) {
+      const oldest = deliveredKeys.values().next().value;
+      deliveredKeys.delete(oldest);
+    }
+  }
+
+  function dedupeKeyOf(entry) {
+    return `${entry.surfaceUuid}:${entry.eventId === null ? 0 : entry.eventId}`;
+  }
+
+  // Route a batch of normalized entries into their sessions' pending buffers:
+  // TTL-expired entries drop here (loudly), and each bucket trims to the cap
+  // (newest kept, loudly). One emit per session per batch.
+  function ingest(entries, nowMs) {
+    const bySession = new Map();
+    for (const entry of entries) {
+      if (!entry.sessionKey) continue;
+      let batch = bySession.get(entry.sessionKey);
+      if (!batch) { batch = []; bySession.set(entry.sessionKey, batch); }
+      batch.push(entry);
+    }
+    for (const [sessionKey, batch] of bySession) {
+      let expired = 0;
+      const fresh = [];
+      for (const entry of batch) {
+        const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+        if (nowMs - basisMs > ttlMs) { expired += 1; continue; }
+        fresh.push(entry);
+      }
+      if (expired > 0) {
+        emitLifecycle("voicemail_expired", "warn", { sessionKey, dropped: expired, ttlMs });
+      }
+      if (fresh.length === 0) continue;
+      const list = pendingBySession.get(sessionKey) || [];
+      list.push(...fresh);
+      if (list.length > VOICEMAIL_PENDING_CAP_PER_SESSION) {
+        const evicted = list.splice(0, list.length - VOICEMAIL_PENDING_CAP_PER_SESSION);
+        emitLifecycle("voicemail_evicted", "warn", { sessionKey, evicted: evicted.length });
+      }
+      pendingBySession.set(sessionKey, list);
+    }
+  }
+
+  // Normalize an owed wake (outbox shape) into the voicemail entry form.
+  function fromOutbox(record) {
+    const surfaceUuid = sanitizeWakeToken(record && record.surfaceUuid);
+    const eventId = coerceInt(record && record.eventId);
+    return {
+      sessionKey: normalizeGlassesSessionKey(record && record.sessionKey) || null,
+      surfaceUuid,
+      eventId,
+      result: sanitizeResult(record && record.result),
+      itemIndex: coerceInt(record && record.itemIndex),
+      queuedAtMs: coerceInt(record && record.queuedAtMs),
+      owedSinceMs: coerceInt(record && record.failedAtMs) ?? coerceInt(record && record.queuedAtMs),
+      idempotencyKey: sanitizeIdempotencyKey(record && record.idempotencyKey),
+      via: record && record.error === "no_dispatch_lane" ? "wake_unavailable" : "wake_failed",
+      staleAfterMs: null,
+      surfaceLive: true,
+    };
+  }
+
+  // Normalize a dead-letter record's events (store shape) into entries.
+  function fromDeadLetter(sessionKey, record) {
+    const surfaceUuid = sanitizeWakeToken(record && record.surfaceUuid);
+    const reason =
+      record && REAP_REASON_ENUM.has(record.reason) ? `reaped:${record.reason}` : "reaped";
+    const staleAfterMs = record && Number.isFinite(record.staleAfterMs) ? record.staleAfterMs : null;
+    const events = record && Array.isArray(record.events) ? record.events : [];
+    return events.map((ev) => {
+      const eventId = coerceInt(ev && ev.eventId);
+      return {
+        sessionKey,
+        surfaceUuid,
+        eventId,
+        result: sanitizeResult(ev && ev.outcome && ev.outcome.result),
+        itemIndex: coerceInt(ev && ev.outcome && ev.outcome.selected_index),
+        queuedAtMs: coerceInt(ev && ev.queuedAtMs),
+        owedSinceMs: coerceInt(ev && ev.queuedAtMs) ?? coerceInt(record && record.reapedAtMs),
+        idempotencyKey: `glasses-voicemail:${surfaceUuid}:${eventId === null ? 0 : eventId}`,
+        via: reason,
+        staleAfterMs,
+        surfaceLive: false,
+      };
+    });
+  }
+
+  function formatEntry(entry, nowMs) {
+    const ageMs = Number.isFinite(entry.queuedAtMs) ? Math.max(0, nowMs - entry.queuedAtMs) : null;
+    const stale =
+      Number.isFinite(entry.staleAfterMs) && ageMs !== null && ageMs > entry.staleAfterMs;
+    const parts = [
+      `- surfaceUuid=${entry.surfaceUuid}`,
+      `eventId=${entry.eventId}`,
+      `result=${entry.result}`,
+      `itemIndex=${entry.itemIndex}`,
+      `queuedAtMs=${entry.queuedAtMs}`,
+      `ageMs=${ageMs}`,
+      `via=${entry.via}`,
+      `idempotencyKey=${entry.idempotencyKey}`,
+    ];
+    if (stale) parts.push("stale=true");
+    parts.push(
+      entry.surfaceLive
+        ? '(surface may still be live: re-render it with update:"patch" to collect)'
+        : "(surface no longer live: treat the refs as the wearer's parked answer to that surface; re-confirm before acting if stale)",
+    );
+    return parts.join(" ");
+  }
+
+  // Sweep ALL buffered buckets for TTL expiry on every build (review round 2):
+  // session keys rotate on relay restarts/reconnects, so abandoned sessions
+  // are a recurring shape — without this, their buckets (each capped, but
+  // unbounded in NUMBER) would outlive them forever. After a sweep, total
+  // buffered memory is bounded by sessions active within one TTL window.
+  function sweepExpired(nowMs) {
+    for (const [key, list] of pendingBySession) {
+      const fresh = list.filter((entry) => {
+        const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+        return nowMs - basisMs <= ttlMs;
+      });
+      const dropped = list.length - fresh.length;
+      if (dropped > 0) {
+        emitLifecycle("voicemail_expired", "warn", { sessionKey: key, dropped, ttlMs });
+      }
+      if (fresh.length === 0) {
+        pendingBySession.delete(key);
+      } else if (dropped > 0) {
+        pendingBySession.set(key, fresh);
+      }
+    }
+  }
+
+  function pendingSessionCount() {
+    return pendingBySession.size;
+  }
+
+  function buildInjection(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
+    if (typeof sessionKey !== "string" || !sessionKey) return null;
+    const nowMs = now();
+    sweepExpired(nowMs);
+
+    // Pull both sources through the bounded ingest. The outbox drain returns
+    // every session's entries — non-target ones land in their own buffers.
+    ingest(
+      [
+        ...drainWakeOutbox().map((record) => fromOutbox(record)),
+        ...(drainDeadLetter(sessionKey) || []).flatMap((r) => fromDeadLetter(sessionKey, r)),
+      ],
+      nowMs,
+    );
+
+    const pending = pendingBySession.get(sessionKey);
+    if (!pending || pending.length === 0) {
+      pendingBySession.delete(sessionKey); // no empty buckets left behind
+      return null;
+    }
+    pendingBySession.delete(sessionKey);
+
+    // In-batch collapse by the canonical per-event key (review P2): the same
+    // parked tap can arrive via the wake outbox AND the dead-letter in one
+    // pass — the dead-letter entry wins (the surface is genuinely gone, so a
+    // "may still be live" line for it would be false).
+    const byEvent = new Map();
+    for (const entry of pending) {
+      const key = dedupeKeyOf(entry);
+      const existing = byEvent.get(key);
+      if (!existing || (existing.surfaceLive && !entry.surfaceLive)) {
+        byEvent.set(key, entry);
+      }
+    }
+
+    const deliverable = [];
+    let dropped = 0;
+    for (const entry of byEvent.values()) {
+      const basisMs = Number.isFinite(entry.owedSinceMs) ? entry.owedSinceMs : nowMs;
+      if (nowMs - basisMs > ttlMs) { dropped += 1; continue; }
+      const key = dedupeKeyOf(entry);
+      if (deliveredKeys.has(key)) continue;
+      rememberDelivered(key);
+      deliverable.push(entry);
+    }
+    if (dropped > 0) {
+      // Loud, never silent: a ✓-acked event aged out while buffered.
+      emitLifecycle("voicemail_expired", "warn", { sessionKey, dropped, ttlMs });
+    }
+    if (deliverable.length === 0) return null;
+
+    // Newest entries are the wearer's most recent intent — keep those when
+    // capping, in chronological order.
+    const shown = deliverable.slice(-maxEntries);
+    const overflow = deliverable.length - shown.length;
+    const lines = [
+      "[ocuclaw glasses-ui voicemail] Plugin-generated notification - NOT the wearer speaking.",
+      "Parked glasses events could not be delivered by a wake turn while you were away:",
+      ...shown.map((entry) => formatEntry(entry, nowMs)),
+    ];
+    if (overflow > 0) lines.push(`(+${overflow} older parked events omitted)`);
+    lines.push("Tapped content is never included here by design.");
+    const fragment = lines.join("\n");
+    emitLifecycle("voicemail_injected", "debug", {
+      sessionKey,
+      entries: shown.length,
+      overflow,
+      chars: fragment.length,
+    });
+    return fragment;
+  }
+
+  return { buildInjection, pendingSessionCount };
+}
+
+// Single line: the CJS emitter strips only `^export default .*;$` (one line).
+export default { createGlassesVoicemail, DEFAULT_VOICEMAIL_TTL_MS, VOICEMAIL_MAX_ENTRIES_PER_INJECTION };

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

@@ -0,0 +1,262 @@
+// Tap-to-wake for parked glasses surfaces (roadmap 6f, §2.6 W).
+//
+// A REAL parked gesture buys ONE agent turn via the plugin's own gateway
+// client (the voice-send lane — request("agent", ...)). This module is a
+// dependency-free LEAF (CJS emitter constraint — see glasses-ui-limits.ts):
+// it builds the wake envelope and owns the arbitration policy; transport is
+// injected (the relay facade's dispatchGlassesWake).
+//
+// Locked contract (§2.6, panel amendments 3-4):
+// - wake payload = STRUCTURED REFERENCES ONLY with explicit non-wearer
+//   provenance framing; never interpolated label text. SECURITY (review
+//   pinned to this ship): every token that reaches the prompt is either
+//   numeric-coerced or charset-filtered ([a-zA-Z0-9._:-], <=64 chars), so a
+//   hostile client cannot smuggle instruction text through the wake lane —
+//   tapped CONTENT only ever reaches the agent through the surface collect
+//   (onReattached delivery), where it arrives as data in a tool result, not
+//   as a user-role message.
+// - origin-typed envelope: ONLY "gesture" enabled at launch. schedule/
+//   threshold/system are reserved categories (event-to-wake is deferred,
+//   not foreclosed) — enabling one later is a policy edit here, not a
+//   schema migration.
+// - voice absorbs wake: an in-flight/imminent genuine turn (voice send,
+//   user send, or an earlier wake's run) suppresses the dispatch; the
+//   parked tap rides that turn's collect instead.
+// - taps during an in-flight wake COALESCE into its delivery — never a
+//   second submission. A per-session cooldown additionally bounds gesture
+//   storms (hostile/buggy client spamming taps) to <=1 turn per window;
+//   suppressed taps stay parked in the 6a event log — bounded, never silent.
+// - failed submission: one retry (same idempotencyKey — the gateway honors
+//   it as the runId, so a double-delivery dedupes), then the durable wake
+//   outbox + a warn lifecycle. Never silent after the ✓-ack (amendment 1);
+//   the parked event itself survives in the surface log / dead-letter
+//   regardless, so the worst case is delayed collect, not loss. The 7b
+//   voicemail leg drains the outbox via enqueueNextTurnInjection.
+
+export const GLASSES_WAKE_ENABLED_ORIGINS = ["gesture"];
+
+export const DEFAULT_WAKE_COOLDOWN_MS = 5_000;
+
+// Outbox bound (review P3 sibling): the no-lane branch pushes per parked tap
+// with no cooldown gate, so a tap storm on a legacy host would otherwise grow
+// this without limit. Newest kept; eviction is loud. The parked events
+// themselves still survive in the surface log / dead-letter — eviction here
+// only forfeits the voicemail NOTICE for the oldest entries.
+export const WAKE_OUTBOX_CAP = 64;
+
+// Busy-signal decay: if no activity update arrives for this long, treat the
+// session as idle again (fail open — a stuck-busy would suppress wakes
+// forever, while a wrongly-idle wake merely queues as the next turn).
+export const DEFAULT_AGENT_TURN_BUSY_DECAY_MS = 180_000;
+
+// SECURITY: charset-FILTERING is not enough — stripping separators from
+// hostile input still concatenates readable instruction words into the
+// prompt ("su-x\" IGNORE ALL..." -> "su-xIGNOREALL..."). Tokens are instead
+// VALIDATED against the exact plugin-minted shape / a closed enum and
+// replaced wholesale when off-pattern, so hostile bytes never pass through.
+const SURFACE_UUID_PATTERN = /^su-[a-z0-9]{4,24}$/i;
+const WAKE_RESULT_ENUM = new Set(["selected", "back"]);
+
+export function sanitizeWakeToken(value) {
+  const raw = String(value == null ? "" : value);
+  return SURFACE_UUID_PATTERN.test(raw) ? raw : "invalid";
+}
+
+function sanitizeWakeResult(value) {
+  return WAKE_RESULT_ENUM.has(value) ? value : "event";
+}
+
+function coerceInt(value) {
+  return Number.isFinite(value) ? Math.floor(value) : null;
+}
+
+export function buildWakeMessage(ref) {
+  const surfaceUuid = sanitizeWakeToken(ref && ref.surfaceUuid);
+  const result = sanitizeWakeResult(ref && ref.result);
+  const eventId = coerceInt(ref && ref.eventId);
+  const itemIndex = coerceInt(ref && ref.itemIndex);
+  const queuedAtMs = coerceInt(ref && ref.queuedAtMs);
+  return [
+    "[ocuclaw glasses-ui wake] Plugin-generated notification - NOT the wearer speaking.",
+    `The wearer tapped a parked glasses surface (origin=gesture). refs: surfaceUuid=${surfaceUuid}`,
+    `eventId=${eventId} result=${result} itemIndex=${itemIndex} queuedAtMs=${queuedAtMs}.`,
+    "Tapped content is not included here by design: re-render that surface",
+    "(update:\"patch\") to collect the parked event(s), then respond as appropriate.",
+  ].join(" ");
+}
+
+// Per-session "an agent turn is in flight or imminent" signal. Fed by the
+// relay: markBusy on every dispatched send (voice/user/wake) and onActivity
+// from the gateway activity stream (normalized phase: start/update = busy
+// refresh, end = idle). Lives here (leaf) so it is unit-testable and shared
+// with the relay without a runtime-module cycle.
+export function createAgentTurnTracker(deps = {}) {
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const busyDecayMs = Number.isFinite(deps.busyDecayMs)
+    ? deps.busyDecayMs
+    : DEFAULT_AGENT_TURN_BUSY_DECAY_MS;
+  const lastSeenBySession = new Map(); // normalized sessionKey -> lastSeenMs
+
+  // One session arrives under TWO key forms: the relay send path marks busy
+  // with the stripped relay key ("ocuclaw:<ts>") while the surface store /
+  // gateway hook contexts use the canonical "agent:<id>:<key>". Normalize so
+  // both name the same busy slot — without this, a tap in the send→run-start
+  // window dispatches a second agent submission during an in-flight genuine
+  // turn (live-proven, 2026-06-12 Wave-1 e2e leg 3a).
+  function normalizeKey(sessionKey) {
+    return sessionKey.replace(/^agent:[^:]+:/, "");
+  }
+
+  function markBusy(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey) return;
+    lastSeenBySession.set(normalizeKey(sessionKey), now());
+  }
+
+  function onActivity(sessionKey, phase) {
+    if (typeof sessionKey !== "string" || !sessionKey) return;
+    if (phase === "end") {
+      lastSeenBySession.delete(normalizeKey(sessionKey));
+      return;
+    }
+    lastSeenBySession.set(normalizeKey(sessionKey), now());
+  }
+
+  function isBusy(sessionKey) {
+    if (typeof sessionKey !== "string" || !sessionKey) return false;
+    const key = normalizeKey(sessionKey);
+    const lastSeen = lastSeenBySession.get(key);
+    if (!Number.isFinite(lastSeen)) return false;
+    if (now() - lastSeen >= busyDecayMs) {
+      lastSeenBySession.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  return { markBusy, onActivity, isBusy };
+}
+
+export function createGlassesWakeController(deps = {}) {
+  const dispatchWake = typeof deps.dispatchWake === "function" ? deps.dispatchWake : null;
+  const isAgentTurnBusy =
+    typeof deps.isAgentTurnBusy === "function" ? deps.isAgentTurnBusy : () => false;
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
+  const wakeCooldownMs = Number.isFinite(deps.wakeCooldownMs)
+    ? deps.wakeCooldownMs
+    : DEFAULT_WAKE_COOLDOWN_MS;
+
+  const inFlightBySession = new Map(); // sessionKey -> promise
+  const lastWakeAtBySession = new Map(); // sessionKey -> ms
+  const outbox = []; // failed/unavailable wakes owed to the 7b voicemail leg
+
+  function pushOutbox(entry) {
+    outbox.push(entry);
+    if (outbox.length > WAKE_OUTBOX_CAP) {
+      const evicted = outbox.splice(0, outbox.length - WAKE_OUTBOX_CAP);
+      emitLifecycle("wake_outbox_evicted", "warn", { evicted: evicted.length });
+    }
+  }
+
+  function refsOnly(ref) {
+    return {
+      sessionKey: typeof ref.sessionKey === "string" ? ref.sessionKey : null,
+      surfaceUuid: sanitizeWakeToken(ref.surfaceUuid),
+      eventId: coerceInt(ref.eventId),
+      result: sanitizeWakeResult(ref.result),
+      itemIndex: coerceInt(ref.itemIndex),
+      // The origin gate below compares against the enum, so a non-enum
+      // origin can never dispatch; keep the raw string for the gate.
+      origin: typeof ref.origin === "string" ? ref.origin : "gesture",
+      queuedAtMs: coerceInt(ref.queuedAtMs),
+    };
+  }
+
+  function suppress(reason, refs) {
+    emitLifecycle("wake_suppressed", "debug", { reason, ...refs });
+    return { dispatched: false, reason };
+  }
+
+  function onParkedGesture(ref) {
+    const refs = refsOnly(ref || {});
+    if (!dispatchWake) {
+      // Wake disabled (legacy host without the relay lane): the parked tap
+      // keeps its collect-on-next-render semantics AND is owed to the 7b
+      // voicemail leg so the next genuine turn hears about it — no longer a
+      // silent early-return. Same gates as a dispatch: enabled origin + a
+      // session to deliver to.
+      if (GLASSES_WAKE_ENABLED_ORIGINS.includes(refs.origin) && refs.sessionKey) {
+        if (refs.queuedAtMs === null) refs.queuedAtMs = now();
+        const idempotencyKey = `glasses-wake:${refs.surfaceUuid}:${refs.eventId === null ? 0 : refs.eventId}`;
+        pushOutbox({
+          ...refs,
+          idempotencyKey,
+          failedAtMs: now(),
+          error: "no_dispatch_lane",
+        });
+        emitLifecycle("wake_unavailable_outboxed", "debug", { ...refs, idempotencyKey });
+      }
+      return { dispatched: false, reason: "no_dispatch_lane" };
+    }
+    if (!GLASSES_WAKE_ENABLED_ORIGINS.includes(refs.origin)) {
+      return suppress("origin_disabled", refs);
+    }
+    const sessionKey = refs.sessionKey;
+    if (!sessionKey) return suppress("no_session", refs);
+    if (isAgentTurnBusy(sessionKey)) {
+      // Voice absorbs wake (§2.6c): the parked event rides the active turn's
+      // collect render or the next genuine turn — no second submission.
+      return suppress("absorbed_by_active_turn", refs);
+    }
+    if (inFlightBySession.has(sessionKey)) {
+      emitLifecycle("wake_coalesced", "debug", refs);
+      return { dispatched: false, reason: "coalesced_into_inflight_wake" };
+    }
+    const lastWakeAt = lastWakeAtBySession.get(sessionKey);
+    if (Number.isFinite(lastWakeAt) && now() - lastWakeAt < wakeCooldownMs) {
+      return suppress("cooldown", refs);
+    }
+
+    if (refs.queuedAtMs === null) refs.queuedAtMs = now();
+    const message = buildWakeMessage(refs);
+    const idempotencyKey = `glasses-wake:${refs.surfaceUuid}:${refs.eventId === null ? 0 : refs.eventId}`;
+    const payload = { sessionKey, message, idempotencyKey };
+    lastWakeAtBySession.set(sessionKey, now());
+    const attempt = () => Promise.resolve(dispatchWake(payload));
+    const flight = attempt()
+      .catch(() => attempt()) // one retry; same idempotencyKey dedupes upstream
+      .then(() => {
+        emitLifecycle("wake_dispatched", "debug", { ...refs, idempotencyKey });
+      })
+      .catch((err) => {
+        // Never silent after the ✓-ack: the owed wake lands in the durable
+        // outbox for the 7b voicemail leg, loudly.
+        pushOutbox({
+          ...refs,
+          idempotencyKey,
+          failedAtMs: now(),
+          error: String((err && err.message) || err),
+        });
+        emitLifecycle("wake_dispatch_failed", "warn", { ...refs, idempotencyKey });
+      })
+      .finally(() => {
+        inFlightBySession.delete(sessionKey);
+      });
+    inFlightBySession.set(sessionKey, flight);
+    return { dispatched: true, idempotencyKey };
+  }
+
+  function peekWakeOutbox() {
+    return outbox.map((r) => ({ ...r }));
+  }
+
+  function drainWakeOutbox() {
+    return outbox.splice(0, outbox.length);
+  }
+
+  return { onParkedGesture, peekWakeOutbox, drainWakeOutbox };
+}
+
+// Single line: the CJS emitter strips only `^export default .*;$` (one line).
+export default { createGlassesWakeController, createAgentTurnTracker, buildWakeMessage, sanitizeWakeToken, GLASSES_WAKE_ENABLED_ORIGINS };

package/dist/tools/session-title-tool.js

@@ -51,21 +51,12 @@ function isEvenAiDedicatedKey(sessionKey) {
 }
 
 function gateReason(sessionKey, deps) {
-  if (typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey)) {
-    return "session_user_locked";
-  }
-  if (
-    typeof deps.isNeuralSessionNamesEnabled === "function" &&
-    !deps.isNeuralSessionNamesEnabled(sessionKey)
-  ) {
-    return "feature_disabled";
-  }
-  // Hard guard against the agent titling a session before the user has sent
-  // their first real message. The synthetic session-starter prompt the agent
-  // sees on /new + the proactive prompt-hook nudge can otherwise tempt the
-  // model into titling from a non-user input (observed: titles like "New
-  // session"). Real user sends are recorded via dispatchOcuClawUserSend ->
-  // sessionService.recordFirstSentUserMessage; the synthetic starter never is.
+  // Explicit-rename-only: the Neural Session Names toggle governs AUTOMATIC
+  // titling (the distiller), not user-requested renames, so feature_disabled is
+  // gone. session_user_locked is gone too — a user who already named a session
+  // must be able to rename it again (the lock only blocks the distiller).
+  // The structural no_active_session / EvenAI-renamable guards live in the
+  // handler body. Only the no-user-message guard remains here.
   if (
     typeof deps.hasRecordedUserMessage === "function" &&
     !deps.hasRecordedUserMessage(sessionKey)
@@ -104,7 +95,9 @@ export function createSessionTitleToolHandler(deps) {
       err.code = blockedReason;
       throw err;
     }
-    const result = await deps.setSessionTitle(sessionKey, validation.spec.title);
+    const result = await deps.setSessionTitle(sessionKey, validation.spec.title, {
+      origin: "user_tool",
+    });
     if (result && result.ok === false) {
       const err = new Error(`${result.code}: ${result.message || "set rejected"}`);
       err.code = result.code;
@@ -115,60 +108,15 @@ export function createSessionTitleToolHandler(deps) {
   return { setSessionTitle };
 }
 
-const TOOL_DESCRIPTION = [
-  "Set a short title for the current chat session (shown in the user's glasses session list).",
+export const TOOL_DESCRIPTION = [
+  "Rename the current chat session (shown in the user's glasses session list).",
   "",
-  "When: first user turn that names any concrete topic — call eagerly. Later, only when the topic has clearly shifted. Skip greetings, acknowledgments, and no-topic messages.",
+  "Call ONLY when the user explicitly asks to rename or retitle the session.",
+  "Automatic titling is handled elsewhere — do not call this proactively.",
   "",
-  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or surrounding quotes.",
-  "",
-  "Do not announce the rename unless the user explicitly asked to retitle.",
+  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or quotes.",
 ].join("\n");
 
-export function createSessionTitlePromptHook(deps) {
-  return function sessionTitleBeforePromptBuild(_event, ctx) {
-    const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
-    if (!sessionKey) return undefined;
-    const title = typeof deps.getSessionTitle === "function" ? deps.getSessionTitle(sessionKey) : null;
-    const userLocked =
-      typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey);
-    const featureEnabled =
-      typeof deps.isNeuralSessionNamesEnabled === "function"
-        ? deps.isNeuralSessionNamesEnabled(sessionKey)
-        : true;
-
-    const fragments = [];
-    if (title) {
-      fragments.push(`Current session title: "${title}".`);
-    }
-    if (userLocked) {
-      fragments.push(
-        "The user has set a custom title; do not call set_session_title.",
-      );
-    } else if (!featureEnabled) {
-      fragments.push(
-        "Neural Topic Distiller is disabled; do not call set_session_title.",
-      );
-    } else if (title) {
-      fragments.push(
-        "Call set_session_title only if the topic has clearly shifted.",
-      );
-    } else {
-      const hasUserMessage =
-        typeof deps.hasRecordedUserMessage !== "function" ||
-        deps.hasRecordedUserMessage(sessionKey);
-      if (hasUserMessage) {
-        fragments.push(
-          "No session title is set yet. Call set_session_title now if the user's latest message names any concrete topic.",
-        );
-      }
-    }
-
-    if (fragments.length === 0) return undefined;
-    return { appendSystemContext: fragments.join(" ") };
-  };
-}
-
 export function registerSessionTitleTool(api, service) {
   if (!api || typeof api.registerTool !== "function") {
     throw new Error("registerSessionTitleTool requires api.registerTool");
@@ -196,14 +144,4 @@ export function registerSessionTitleTool(api, service) {
       };
     },
   });
-
-  if (typeof api.on === "function") {
-    const hook = createSessionTitlePromptHook({
-      getSessionTitle: (sessionKey) => service.getSessionTitle(sessionKey),
-      isSessionUserLocked: (sessionKey) => service.isSessionUserLocked(sessionKey),
-      isNeuralSessionNamesEnabled: (sessionKey) => service.isNeuralSessionNamesEnabled(sessionKey),
-      hasRecordedUserMessage: (sessionKey) => service.hasRecordedUserMessage(sessionKey),
-    });
-    api.on("before_prompt_build", hook);
-  }
 }