ocuclaw 0.1.0 → 1.3.0

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

@@ -0,0 +1,1147 @@
+// Glasses UI tool: lets the agent paint an interactive surface on the user's
+// Even G2 glasses HUD instead of replying with text. Plain JSON Schema is used
+// for the tool parameters because the plugin build is a regex-based emitter
+// that has no access to typebox at runtime; OpenClaw consumes JSON Schema
+// directly anyway.
+
+import { validateTemplate } from "./glasses-ui-template.js";
+import { createGlassesUiCronEngine } from "./glasses-ui-cron.js";
+import {
+  executeShellRecipe,
+  executeHttpRecipe,
+  executeLlmRecipe,
+  executeSystemStatsRecipe,
+} from "./glasses-ui-recipes.js";
+import { createPendingRenderMap, createSurfaceStore, isTerminalOutcome } from "./glasses-ui-surfaces.js";
+import { createPaintFloorCoalescer, DEFAULT_PAINT_FLOOR_MS } from "./glasses-ui-paint-floor.js";
+import { GLASSES_UI_LIMITS } from "./glasses-ui-limits.js";
+import {
+  getKindDescriptor,
+  listKindStrings,
+  buildOneOfBranches,
+} from "./glasses-ui-descriptors.js";
+
+// Re-exported so existing consumers/tests that import these from this module
+// keep working after the extractions (spec §Changes A — extraction is behavior-
+// preserving). Canonical homes: createPendingRenderMap/createSurfaceStore ->
+// ./glasses-ui-surfaces.js, GLASSES_UI_LIMITS -> ./glasses-ui-limits.js. Kept as
+// ONE bare `export {}` statement because the CJS emitter (scripts/build.mjs)
+// strips only the first such statement — a second would survive into the .cjs
+// as invalid syntax. createPendingRenderMap is the Phase-1 alias of the single
+// createSurfaceStore (see glasses-ui-surfaces.ts).
+export { createPendingRenderMap, createSurfaceStore, GLASSES_UI_LIMITS };
+
+export const GLASSES_UI_REFRESH_LIMITS = {
+  intervalMsMin: { shell: 1000, http: 1000, "system-stats": 1000, "llm-cli": 60_000, "llm-api": 30_000 },
+  intervalMsMax: 3_600_000,
+  maxDurationMsMin: 10_000,
+  maxDurationMsMax: 7_200_000,
+  maxDurationMsDefault: 30 * 60 * 1000,
+  maxConsecutiveFailuresMin: 1,
+  maxConsecutiveFailuresMax: 100,
+  maxConsecutiveFailuresDefault: 5,
+  shellHttpTimeoutMsMin: 1000,
+  shellHttpTimeoutMsMax: 30_000,
+  shellHttpTimeoutMsDefault: 10_000,
+  llmTimeoutMsMin: 5000,
+  llmTimeoutMsMax: 60_000,
+  llmTimeoutMsDefault: 30_000,
+  outputCapBytesMin: 1024,
+  outputCapBytesMax: 1_048_576,
+  outputCapBytesDefault: 65_536,
+  maxOutputTokensMin: 16,
+  maxOutputTokensMax: 1000,
+  maxOutputTokensDefault: 200,
+  // Cap on a single template string (body or one items entry). The
+  // substituted OUTPUT is clamped to bodyMax/itemMax at runtime, but a huge
+  // template itself is wasted work — 4KB is generous for any HUD line.
+  templateMaxChars: 4096,
+  // L0' system-stats: bounds on the optional CPU-sample window (ms).
+  systemStatsWindowMsMin: 50,
+  systemStatsWindowMsMax: 1000,
+};
+
+const ON_ERROR_VALUES = new Set(["keep_last", "show_error", "stop"]);
+
+function llmIntervalMinForBackend(backend) {
+  if (backend === "claude-cli") {
+    return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-cli"];
+  }
+  return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-api"];
+}
+
+// The effective per-tick interval floor is the larger of the tier minimum and
+// the paint-floor coalescer's cadence (Spike D, 150ms) — no tick may schedule
+// faster than the glass can paint. Today every tier min already exceeds 150ms,
+// so this only guards the floor from ever relaxing below the coalescer cadence.
+function effectiveIntervalFloorMs(tierMinMs) {
+  return Math.max(tierMinMs, DEFAULT_PAINT_FLOOR_MS);
+}
+
+export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
+  if (refresh === undefined || refresh === null) return { ok: true, refresh: undefined };
+  if (typeof refresh !== "object" || Array.isArray(refresh)) {
+    return { ok: false, code: "refresh_invalid_recipe", message: "refresh must be an object" };
+  }
+  const cfg = glassesUiLiveCfg && typeof glassesUiLiveCfg === "object" ? glassesUiLiveCfg : {};
+  if (cfg.enabled === false) {
+    return { ok: false, code: "refresh_disabled", message: "glassesUiLive is disabled by operator config" };
+  }
+  const recipe = refresh.recipe;
+  if (!recipe || typeof recipe !== "object") {
+    return { ok: false, code: "refresh_invalid_recipe", message: "refresh.recipe is required" };
+  }
+  const kind = recipe.kind;
+  if (kind !== "shell" && kind !== "http" && kind !== "llm" && kind !== "system-stats") {
+    return { ok: false, code: "refresh_invalid_recipe", message: `recipe.kind must be shell/http/llm/system-stats, got ${JSON.stringify(kind)}` };
+  }
+  // Sanitize the recipe — clamp/reject agent-supplied timeoutMs / outputCapBytes
+  // / maxOutputTokens to declared bounds, copy known fields only. The returned
+  // `refresh.recipe` is this sanitized version, never the raw input — so the
+  // executors at run-time see vetted values.
+  const sanitizedRecipe = { kind };
+  const bounded = (raw, min, max) => {
+    if (!Number.isFinite(raw)) return null;
+    if (raw < min || raw > max) return undefined; // signal out-of-range
+    return Math.floor(raw);
+  };
+  if (kind === "shell") {
+    if (cfg.shellEnabled === false) return { ok: false, code: "refresh_disabled", message: "shell recipes disabled" };
+    if (typeof recipe.command !== "string" || !recipe.command.trim()) {
+      return { ok: false, code: "refresh_invalid_recipe", message: "shell recipe requires command (non-empty string)" };
+    }
+    sanitizedRecipe.command = recipe.command;
+    if (recipe.timeoutMs !== undefined) {
+      const v = bounded(recipe.timeoutMs, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.timeoutMs ${recipe.timeoutMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin}..${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax}]` };
+      if (v !== null) sanitizedRecipe.timeoutMs = v;
+    }
+    if (recipe.outputCapBytes !== undefined) {
+      const v = bounded(recipe.outputCapBytes, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMin, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.outputCapBytes ${recipe.outputCapBytes} out of bounds` };
+      if (v !== null) sanitizedRecipe.outputCapBytes = v;
+    }
+  } else if (kind === "http") {
+    if (cfg.httpEnabled === false) return { ok: false, code: "refresh_disabled", message: "http recipes disabled" };
+    if (typeof recipe.url !== "string" || !recipe.url.trim()) {
+      return { ok: false, code: "refresh_invalid_recipe", message: "http recipe requires url (non-empty string)" };
+    }
+    sanitizedRecipe.url = recipe.url;
+    if (typeof recipe.method === "string") sanitizedRecipe.method = recipe.method;
+    if (recipe.headers && typeof recipe.headers === "object") sanitizedRecipe.headers = recipe.headers;
+    if (typeof recipe.body === "string") sanitizedRecipe.body = recipe.body;
+    if (typeof recipe.jsonPath === "string") sanitizedRecipe.jsonPath = recipe.jsonPath;
+    if (recipe.timeoutMs !== undefined) {
+      const v = bounded(recipe.timeoutMs, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `http.timeoutMs ${recipe.timeoutMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin}..${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax}]` };
+      if (v !== null) sanitizedRecipe.timeoutMs = v;
+    }
+    if (recipe.outputCapBytes !== undefined) {
+      const v = bounded(recipe.outputCapBytes, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMin, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `http.outputCapBytes ${recipe.outputCapBytes} out of bounds` };
+      if (v !== null) sanitizedRecipe.outputCapBytes = v;
+    }
+  } else if (kind === "llm") {
+    if (cfg.llmEnabled === false) return { ok: false, code: "refresh_disabled", message: "llm recipes disabled" };
+    if (typeof recipe.prompt !== "string" || !recipe.prompt.trim()) {
+      return { ok: false, code: "refresh_invalid_recipe", message: "llm recipe requires prompt (non-empty string)" };
+    }
+    if (typeof recipe.model === "string" && recipe.model.trim() && cfg.allowAgentModelOverride !== true) {
+      return { ok: false, code: "refresh_llm_model_override_denied", message: "agent model override denied by operator config" };
+    }
+    sanitizedRecipe.prompt = recipe.prompt;
+    if (typeof recipe.systemPrompt === "string") sanitizedRecipe.systemPrompt = recipe.systemPrompt;
+    if (typeof recipe.model === "string") sanitizedRecipe.model = recipe.model;
+    if (recipe.maxOutputTokens !== undefined) {
+      const v = bounded(recipe.maxOutputTokens, GLASSES_UI_REFRESH_LIMITS.maxOutputTokensMin, GLASSES_UI_REFRESH_LIMITS.maxOutputTokensMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `llm.maxOutputTokens ${recipe.maxOutputTokens} out of bounds` };
+      if (v !== null) sanitizedRecipe.maxOutputTokens = v;
+    }
+  } else if (kind === "system-stats") {
+    // Built-in tier: host RAM/CPU via the in-process structured reader. NOT gated
+    // by httpEnabled/shellEnabled/llmEnabled — it touches no network, no shell, no
+    // model. Only the master `enabled` switch (checked above) governs it. Do NOT
+    // add a cfg.*Enabled gate here (intentional — Phase 3 design).
+    if (recipe.sampleWindowMs !== undefined) {
+      const v = bounded(recipe.sampleWindowMs, GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMin, GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMax);
+      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `system-stats.sampleWindowMs ${recipe.sampleWindowMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMin}..${GLASSES_UI_REFRESH_LIMITS.systemStatsWindowMsMax}]` };
+      if (v !== null) sanitizedRecipe.sampleWindowMs = v;
+    }
+  }
+
+  // Interval bounds.
+  const intervalMs = refresh.intervalMs;
+  if (!Number.isFinite(intervalMs)) {
+    return { ok: false, code: "refresh_invalid_recipe", message: "refresh.intervalMs is required" };
+  }
+  const minForKind =
+    kind === "llm"
+      ? llmIntervalMinForBackend(cfg.tickBackend)
+      : GLASSES_UI_REFRESH_LIMITS.intervalMsMin[kind];
+  const minEffective = effectiveIntervalFloorMs(minForKind);
+  if (intervalMs < minEffective) {
+    return {
+      ok: false,
+      code: "refresh_interval_too_low",
+      message: `intervalMs ${intervalMs} below minimum ${minEffective} for ${kind}${kind === "llm" ? ` (${cfg.tickBackend})` : ""}`,
+    };
+  }
+  if (intervalMs > GLASSES_UI_REFRESH_LIMITS.intervalMsMax) {
+    return { ok: false, code: "refresh_interval_too_high", message: `intervalMs ${intervalMs} above max ${GLASSES_UI_REFRESH_LIMITS.intervalMsMax}` };
+  }
+
+  // Duration.
+  const maxDurationMs = Number.isFinite(refresh.maxDurationMs)
+    ? refresh.maxDurationMs
+    : GLASSES_UI_REFRESH_LIMITS.maxDurationMsDefault;
+  if (maxDurationMs < GLASSES_UI_REFRESH_LIMITS.maxDurationMsMin || maxDurationMs > GLASSES_UI_REFRESH_LIMITS.maxDurationMsMax) {
+    return { ok: false, code: "refresh_duration_too_high", message: `maxDurationMs ${maxDurationMs} out of bounds` };
+  }
+
+  // onError.
+  const onError = typeof refresh.onError === "string" ? refresh.onError : "keep_last";
+  if (!ON_ERROR_VALUES.has(onError)) {
+    return { ok: false, code: "refresh_invalid_recipe", message: `onError must be keep_last/show_error/stop` };
+  }
+
+  // Templates.
+  const targets = refresh.targets && typeof refresh.targets === "object" ? refresh.targets : {};
+  if (typeof targets.body === "string") {
+    if (targets.body.length > GLASSES_UI_REFRESH_LIMITS.templateMaxChars) {
+      return { ok: false, code: "refresh_template_invalid", message: `targets.body template exceeds ${GLASSES_UI_REFRESH_LIMITS.templateMaxChars} chars` };
+    }
+    const v = validateTemplate(targets.body);
+    if (!v.ok) return v;
+  }
+  if (Array.isArray(targets.items)) {
+    // Cap array length — only the first maxItems survive the runtime slice,
+    // so a 100k-entry array would burn CPU substituting templates that are
+    // immediately discarded. Reject (rather than truncate) so the agent gets
+    // clear feedback that it over-supplied.
+    if (targets.items.length > GLASSES_UI_LIMITS.maxItems) {
+      return {
+        ok: false,
+        code: "refresh_invalid_recipe",
+        message: `targets.items has ${targets.items.length} entries; max is ${GLASSES_UI_LIMITS.maxItems}`,
+      };
+    }
+    for (let i = 0; i < targets.items.length; i += 1) {
+      const item = targets.items[i];
+      if (typeof item === "string") {
+        if (item.length > GLASSES_UI_REFRESH_LIMITS.templateMaxChars) {
+          return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}] template exceeds ${GLASSES_UI_REFRESH_LIMITS.templateMaxChars} chars` };
+        }
+        const v = validateTemplate(item);
+        if (!v.ok) return v;
+      } else if (item && typeof item === "object" && !Array.isArray(item)) {
+        // {label, body?} per-item templates (list_with_details detail bodies).
+        if (typeof item.label !== "string") {
+          return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}].label must be a string template` };
+        }
+        for (const field of ["label", "body"]) {
+          const tpl = item[field];
+          if (tpl === undefined) continue;
+          if (typeof tpl !== "string") {
+            return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}].${field} must be a string template` };
+          }
+          if (tpl.length > GLASSES_UI_REFRESH_LIMITS.templateMaxChars) {
+            return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}].${field} template exceeds ${GLASSES_UI_REFRESH_LIMITS.templateMaxChars} chars` };
+          }
+          const v = validateTemplate(tpl);
+          if (!v.ok) return v;
+        }
+      } else {
+        return { ok: false, code: "refresh_template_invalid", message: `targets.items[${i}] must be a string or {label, body} template` };
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    refresh: {
+      recipe: sanitizedRecipe,
+      intervalMs,
+      targets,
+      onError,
+      maxDurationMs,
+      maxConsecutiveFailures: Number.isFinite(refresh.maxConsecutiveFailures)
+        ? Math.max(1, Math.min(100, Math.floor(refresh.maxConsecutiveFailures)))
+        : GLASSES_UI_REFRESH_LIMITS.maxConsecutiveFailuresDefault,
+    },
+  };
+}
+
+const updateSchemaForToolParams = {
+  type: "string",
+  enum: ["patch", "replace", "push"],
+  description:
+    "How this render relates to the current surface. " +
+    "\"patch\": change some fields of the current screen (cron keeps ticking). " +
+    "\"replace\" (default): swap the whole current screen content (no back-target). " +
+    "\"push\": stack a new screen; the parent is retained and its cron pauses.",
+};
+
+const refreshSchemaForToolParams = {
+  type: "object",
+  description: "Optional periodic refresh policy; turns this surface into a live-updating one.",
+  required: ["recipe", "intervalMs"],
+  properties: {
+    intervalMs: { type: "integer", minimum: 1000, maximum: 3_600_000 },
+    maxDurationMs: { type: "integer", minimum: 10_000, maximum: 7_200_000 },
+    maxConsecutiveFailures: { type: "integer", minimum: 1, maximum: 100 },
+    onError: { type: "string", enum: ["keep_last", "show_error", "stop"] },
+    targets: {
+      type: "object",
+      properties: {
+        body: { type: "string" },
+        items: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              { type: "object", required: ["label"], properties: { label: { type: "string" }, body: { type: "string" } } },
+            ],
+          },
+        },
+      },
+    },
+    recipe: {
+      oneOf: [
+        {
+          type: "object",
+          required: ["kind", "command"],
+          properties: {
+            kind: { const: "shell" },
+            command: { type: "string" },
+            timeoutMs: { type: "integer" },
+            outputCapBytes: { type: "integer" },
+          },
+        },
+        {
+          type: "object",
+          required: ["kind", "url"],
+          properties: {
+            kind: { const: "http" },
+            url: { type: "string" },
+            method: { type: "string", enum: ["GET", "POST"] },
+            headers: { type: "object" },
+            body: { type: "string" },
+            jsonPath: { type: "string" },
+            timeoutMs: { type: "integer" },
+            outputCapBytes: { type: "integer" },
+          },
+        },
+        {
+          type: "object",
+          required: ["kind", "prompt"],
+          properties: {
+            kind: { const: "llm" },
+            prompt: { type: "string" },
+            systemPrompt: { type: "string" },
+            model: { type: "string" },
+            maxOutputTokens: { type: "integer" },
+          },
+        },
+        {
+          type: "object",
+          required: ["kind"],
+          properties: {
+            kind: { const: "system-stats" },
+            sampleWindowMs: { type: "integer", minimum: 50, maximum: 1000 },
+          },
+        },
+      ],
+    },
+  },
+};
+
+// Top-level `properties` lists every field a valid spec may carry across all
+// `kind`s. OpenClaw's Anthropic provider strips `oneOf` when building
+// `input_schema` (it keeps only top-level `properties` + `required`), so
+// without this flat union the model would see `properties: {}` and have to
+// guess the shape from the tool description alone. Per-kind shape constraints
+// are still enforced by `validateGlassesUiSpec` and the JSON Schema `oneOf`
+// below for clients that honor it.
+export const glassesUiParametersSchema = {
+  type: "object",
+  required: ["kind"],
+  properties: {
+    kind: {
+      type: "string",
+      // Enum derived from the descriptor registry (enum order). Adding a kind
+      // is one descriptor with no edit here (spec §Modularity).
+      enum: listKindStrings(),
+      description:
+        "Surface kind. Each kind expects a different items/body shape — see " +
+        "the tool description for examples.",
+    },
+    title: {
+      type: "string",
+      maxLength: GLASSES_UI_LIMITS.titleMax,
+      description: "Optional ≤64-char title shown at the top of the surface.",
+    },
+    body: {
+      type: "string",
+      maxLength: GLASSES_UI_LIMITS.bodyMax,
+      description:
+        "Required when kind=\"text_surface\". The ≤1000-char block of text to " +
+        "display. Ignored for the list kinds.",
+    },
+    items: {
+      type: "array",
+      maxItems: GLASSES_UI_LIMITS.maxItems,
+      description:
+        "Required when kind=\"list_surface\" or kind=\"list_with_details_surface\". " +
+        "For list_surface, an array of plain strings (≤64 chars each), e.g. " +
+        "[\"Monday\", \"Tuesday\"]. For list_with_details_surface, an array of " +
+        "{label, body?} objects (label ≤64 chars, body ≤200 chars), e.g. " +
+        "[{\"label\": \"Monday\", \"body\": \"Cloudy 14C, light rain pm\"}, " +
+        "{\"label\": \"Tuesday\", \"body\": \"Sunny 19C\"}]. Up to 20 items.",
+    },
+    // refresh must be top-level too — the Anthropic provider strips `oneOf`
+    // (see the block comment above), so a refresh entry that lives only in
+    // the oneOf branches is invisible on that path and the live-refresh
+    // feature becomes unreachable. The per-branch copies below stay for
+    // clients that honor oneOf.
+    refresh: refreshSchemaForToolParams,
+    // update is the render-vs-current-surface move (patch/replace/push,
+    // default replace). Top-level for the same Anthropic-strips-oneOf reason as
+    // refresh; mirrored into every oneOf branch below.
+    update: updateSchemaForToolParams,
+  },
+  // oneOf is assembled from the descriptor registry (one branch per kind, in
+  // enum order). Each branch's `refresh` slot — declared `undefined` in the
+  // descriptor's schemaBranch — is filled here with the shared refresh schema
+  // so the per-branch shape matches today's hand-written one (the tool owns
+  // refreshSchemaForToolParams; the descriptor only declares the slot). `update`
+  // is mirrored into every branch the same way.
+  oneOf: buildOneOfBranches().map((branch) => ({
+    ...branch,
+    properties: {
+      ...branch.properties,
+      refresh: refreshSchemaForToolParams,
+      update: updateSchemaForToolParams,
+    },
+  })),
+};
+
+export function validateGlassesUiSpec(input) {
+  if (!input || typeof input !== "object") {
+    return { ok: false, code: "invalid_kind", message: "spec must be an object" };
+  }
+  const obj = input;
+  // Dispatch by kind STRING through the descriptor registry. "No descriptor for
+  // kind" reproduces today's invalid_kind. Per-kind validation (incl. the
+  // shared title check, which each descriptor runs first) lives in the
+  // descriptor's validateSpec, so behavior is identical to the old switch.
+  const descriptor = getKindDescriptor(obj.kind);
+  if (!descriptor) {
+    return {
+      ok: false,
+      code: "invalid_kind",
+      message:
+        `kind must be "text_surface", "list_surface", or "list_with_details_surface"; ` +
+        `got ${JSON.stringify(obj.kind)}`,
+    };
+  }
+  return descriptor.validateSpec(obj);
+}
+
+import { randomUUID } from "node:crypto";
+
+// Mirror of even-ai-model-hook's session classifier. Inlined to avoid a
+// cross-file CJS dependency (even-ai-model-hook is ESM-only in dist).
+// Keep these constants in sync with even-ai-model-hook.ts.
+const EVEN_AI_THROWAWAY_SESSION_PREFIX = "ocuclaw:even-ai:";
+const EVEN_AI_DEFAULT_DEDICATED_SESSION_KEY = "ocuclaw:even-ai";
+
+function normalizeEvenAiSessionKey(value) {
+  if (typeof value !== "string") return "";
+  return value.trim().toLowerCase();
+}
+
+export function isEvenAiAgentSession(sessionKey, dedicatedSessionKey) {
+  const normalized = normalizeEvenAiSessionKey(sessionKey);
+  if (!normalized) return false;
+  if (
+    normalized === EVEN_AI_DEFAULT_DEDICATED_SESSION_KEY ||
+    normalized.startsWith(EVEN_AI_THROWAWAY_SESSION_PREFIX)
+  ) {
+    return true;
+  }
+  const normalizedDedicated = normalizeEvenAiSessionKey(dedicatedSessionKey);
+  return !!normalizedDedicated && normalized === normalizedDedicated;
+}
+
+// Default timeout when no per-call or per-handler timeout is provided.
+// Bounds the orphan-tool_use corruption window (see Family 2 in the OpenClaw
+// task-runs zombies / orphan tool_use memory): if a render_glasses_ui call
+// stays unresolved this long, the plugin returns { result: "timeout" } so
+// the agent's runtime persists a matching tool_result and the next turn's
+// session replay won't 400 on an unmatched tool_use block.
+export const DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS = 30 * 60 * 1000;
+
+export function createGlassesUiToolHandler(deps) {
+  // The single live surface store is constructed below (after the cron engine,
+  // which it delegates pause/resume/stop to). There is never a separate pending
+  // map alongside it (spec §Core model — one store).
+  // Short-lived per-surface capture used to read the cron's merged outcome
+  // (ticks{}, lastBody, lastItems, ...extra) when runDynamicUi stops the
+  // cron after a user dismissal (pending already resolved with a user-only
+  // outcome that lacks ticks). Cleared immediately after stop returns.
+  const capturedCronOutcome = new Map();
+  const newSurfaceId =
+    deps && typeof deps.newSurfaceId === "function"
+      ? deps.newSurfaceId
+      : () => `ui-${randomUUID().slice(0, 8)}`;
+
+  // Permanent glasses.lifecycle observability (nav reconcile + cron pause/
+  // resume/tick). No-op when the dep is absent (tests) or the debug category is
+  // disabled. See docs/superpowers/findings/2026-05-30-glasses-ui-phase4-hardware.md.
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+
+  // Resolve the handler-wide default timeout. Per-call timeouts may still
+  // override this via params.timeoutMs.
+  function resolveHandlerTimeoutMs() {
+    if (!deps || deps.timeoutMs === undefined) return DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
+    if (typeof deps.timeoutMs === "function") {
+      const v = deps.timeoutMs();
+      return Number.isFinite(v) ? v : DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
+    }
+    return Number.isFinite(deps.timeoutMs) ? deps.timeoutMs : DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
+  }
+
+  // The single plugin->glass send chokepoint (Spike D). EVERY send — the
+  // initial render frame and every cron surface_update — routes through this
+  // trailing-edge coalescer so bursts collapse to ≤1 frame per 150ms and shed
+  // under BLE backpressure. A { __render } sentinel is a full container
+  // rebuild; a plain field patch is a surface_update.
+  const paintFloor = createPaintFloorCoalescer({
+    // Tests may inject paintFloorMs: 0 to disable coalescing (every enqueue is
+    // a leading-edge send) so synchronous send-ordering assertions hold;
+    // production uses the 150ms Spike-D cadence.
+    paintFloorMs: Number.isFinite(deps.paintFloorMs) ? deps.paintFloorMs : DEFAULT_PAINT_FLOOR_MS,
+    send: ({ surfaceId, sessionKey, patch }) => {
+      if (patch && patch.__render) {
+        deps.relay.sendGlassesUiRender({ sessionKey, surfaceId, depth: patch.__depth, spec: patch.__spec });
+      } else {
+        deps.relay.sendGlassesUiSurfaceUpdate({ sessionKey, surfaceId, patch });
+      }
+    },
+    isUnderBackpressure: typeof deps.isUnderBackpressure === "function" ? deps.isUnderBackpressure : () => false,
+  });
+
+  const cronEngine = createGlassesUiCronEngine({
+    emitLifecycle,
+    monotonicNowMs: () => performance.now(),
+    executeRecipe: async (recipe, ctx) => {
+      if (recipe.kind === "shell") return executeShellRecipe(recipe);
+      if (recipe.kind === "http") return executeHttpRecipe(recipe);
+      if (recipe.kind === "system-stats") return executeSystemStatsRecipe(recipe);
+      if (recipe.kind === "llm") return executeLlmRecipe(recipe, ctx);
+      return { error: `unknown recipe kind: ${recipe.kind}` };
+    },
+    glassesUiLimits: GLASSES_UI_LIMITS,
+    sendSurfaceUpdate: (params) => paintFloor.enqueue({ surfaceId: params.surfaceId, sessionKey: params.sessionKey, patch: params.patch }),
+    resolveLlmCtx: (state) => {
+      const cfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : {};
+      const agentModel =
+        typeof state.recipe.model === "string" && state.recipe.model.trim() && cfg.allowAgentModelOverride === true
+          ? state.recipe.model.trim()
+          : null;
+      const model = agentModel || cfg.tickModel || "";
+      const maxOutputTokens = Number.isFinite(state.recipe.maxOutputTokens)
+        ? Math.min(state.recipe.maxOutputTokens, cfg.tickMaxOutputTokens || 200)
+        : (cfg.tickMaxOutputTokens || 200);
+      return {
+        backend: cfg.tickBackend || "claude-cli",
+        model,
+        baseUrl: cfg.tickApiBaseUrl || "",
+        apiKey: deps.resolveLlmApiKey ? deps.resolveLlmApiKey(model) : "",
+        maxOutputTokens,
+        previousBody: state.lastBody || "",
+      };
+    },
+  });
+
+  // The SINGLE live surface store (spec §Core model). Constructed after the
+  // cron engine so it can delegate pause/resume/stop; id minting reuses the
+  // handler's minter. Replaces the Phase-1 pending map — never a second store.
+  const surfaceStore = createSurfaceStore({
+    pauseCron: (id) => cronEngine.pause(id),
+    resumeCron: (id) => cronEngine.resume(id),
+    // stopCron fires on every surface teardown (replace swap, popBack child,
+    // exit, drain). Dispose the paint-floor coalescer entry too so an armed
+    // trailing flush can't paint a stale surface_update onto the now-visible
+    // parent/chat after a back/pop, and the per-surface coalescer state doesn't
+    // leak across a long push/replace session. (pauseCron on push does NOT
+    // dispose — the parent resumes.)
+    stopCron: (id) => {
+      cronEngine.stop(id, { result: "preempted" });
+      paintFloor.dispose(id);
+    },
+    mintSurfaceId: newSurfaceId,
+  });
+
+  deps.relay.onGlassesUiResult((msg) => {
+    if (!msg || typeof msg.surfaceId !== "string" || !msg.outcome) return;
+    const terminal = isTerminalOutcome(msg.outcome);
+    if (terminal && cronEngine.isActive(msg.surfaceId)) {
+      // Terminal with a live cron: stop the cron, merging its tick stats into
+      // the outcome via capturedCronOutcome, then settle the in-flight call (or
+      // queue the terminal so the next render discards-for-exit).
+      let merged = msg.outcome;
+      capturedCronOutcome.set(msg.surfaceId, (cronOutcome) => { merged = cronOutcome; });
+      cronEngine.stop(msg.surfaceId, msg.outcome);
+      capturedCronOutcome.delete(msg.surfaceId);
+      if (!surfaceStore.resolve(msg.surfaceId, merged)) {
+        surfaceStore.queueEvent(msg.surfaceId, merged);
+      }
+      return;
+    }
+    // Nonterminal (selected/back): settle the call if one is pending; otherwise
+    // the surface is in visible_awaiting_agent — queue last-wins so the agent's
+    // next render delivers the latest event (spec §Tool-call accounting). A
+    // terminal with no live cron also lands here (queue → next render tears down).
+    if (!surfaceStore.resolve(msg.surfaceId, msg.outcome)) {
+      surfaceStore.queueEvent(msg.surfaceId, msg.outcome);
+    }
+  });
+
+  async function runDynamicUi(params) {
+    const validation = validateGlassesUiSpec(params.spec);
+    if (!validation.ok) {
+      emitLifecycle("render_rejected", "warn", {
+        surfaceId: params && typeof params.surfaceId === "string" ? params.surfaceId : null,
+        code: validation.code || "invalid_spec",
+        reason: validation.error || validation.message || "spec validation failed",
+      });
+      const err = new Error(`${validation.code}: ${validation.message}`);
+      err.code = validation.code;
+      throw err;
+    }
+    const sessionKey =
+      typeof params.sessionKey === "string" && params.sessionKey.trim()
+        ? params.sessionKey.trim()
+        : "main";
+    if (typeof deps.isSessionConnected === "function" && !deps.isSessionConnected(sessionKey)) {
+      const err = new Error(
+        "glasses_not_connected: no Even glasses client connected for this session",
+      );
+      err.code = "glasses_not_connected";
+      throw err;
+    }
+
+    let refreshValidated;
+    if (params.spec && params.spec.refresh !== undefined) {
+      const glassesUiLiveCfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : { enabled: true };
+      const v = validateRefreshSpec(params.spec.refresh, glassesUiLiveCfg);
+      if (!v.ok) {
+        const err = new Error(`${v.code}: ${v.message}`);
+        err.code = v.code;
+        throw err;
+      }
+      refreshValidated = v.refresh;
+    }
+
+    const depth = Number.isFinite(params.depth) ? Math.max(1, Math.floor(params.depth)) : 1;
+    const update =
+      params.spec && (params.spec.update === "patch" || params.spec.update === "push")
+        ? params.spec.update
+        : "replace";
+    // The plugin owns surfaceIds (spec §Core model). applyRender derives the
+    // target from the session's current top: patch/replace reuse the top id
+    // (re-attach in place), push mints a child + pauses the parent cron, the
+    // first render mints a root. This is the single place a surfaceId is bound.
+    const applied = surfaceStore.applyRender(sessionKey, {
+      update,
+      kind: validation.spec.kind,
+    });
+    const surfaceId = applied.surfaceId;
+    const promise = surfaceStore.register(sessionKey, surfaceId, { kind: validation.spec.kind });
+    // Re-attach flush (last-wins queue / latched exit): only for a patch/replace
+    // onto an already-attached surface (the visible_awaiting_agent window can
+    // only exist on a surface that previously resolved a call). A fresh
+    // root/push has an empty queue and stays visible_pending. onReattached
+    // delivers any queued nonterminal against the call we just established, or —
+    // if an exit was latched — returns "discarded_for_exit" so this render is
+    // dropped and the surface tears down (spec §Tool-call accounting). This is
+    // move-independent: replace (the schema default) carries the prior entry's
+    // latched exit / queued event forward (Task 8 makeEntry).
+    if (applied.mode === "patch" || applied.mode === "replace") {
+      const reattach = surfaceStore.onReattached(surfaceId);
+      if (reattach === "discarded_for_exit") {
+        // onReattached already resolved THIS render's pending call with the
+        // latched terminal outcome (so `promise` is settled). Tear down instead
+        // of painting the discarded render.
+        if (cronEngine.isActive(surfaceId)) cronEngine.stop(surfaceId, { result: "dismissed" });
+        surfaceStore.exit(sessionKey);
+        return promise;
+      }
+    }
+
+    // Initial render uses the agent's seed (instant). Routed through the
+    // paint-floor coalescer as a leading-edge render sentinel so it shares the
+    // single send chokepoint (a render supersedes any queued field patch for
+    // this surface; see glasses-ui-paint-floor mergePatch).
+    paintFloor.enqueue({
+      surfaceId,
+      sessionKey,
+      patch: { __render: true, __depth: depth, __spec: validation.spec },
+    });
+
+    // Live-refresh path: kick off the cron in parallel. A `patch` onto an
+    // already-ticking surface leaves its cron alone (spec: "cron keeps
+    // ticking"); every other move (replace/push/root) starts a cron for the new
+    // content when this render carries a refresh.
+    if (refreshValidated && !(update === "patch" && cronEngine.isActive(surfaceId))) {
+      // Pre-warm the LLM API key cache so tick 1 doesn't see an empty key
+      // and fail the smoke test. For non-LLM recipes this is a no-op.
+      // For the claude-cli backend the resolved key is "" and not consumed
+      // (the CLI auths via its own login), so the prewarm is a harmless
+      // no-op there.
+      if (refreshValidated.recipe.kind === "llm" && typeof deps.prewarmLlmApiKey === "function") {
+        const cfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : {};
+        const agentModel =
+          typeof refreshValidated.recipe.model === "string" &&
+          refreshValidated.recipe.model.trim() &&
+          cfg.allowAgentModelOverride === true
+            ? refreshValidated.recipe.model.trim()
+            : null;
+        const prewarmModel = agentModel || cfg.tickModel || "";
+        if (prewarmModel) {
+          try {
+            await deps.prewarmLlmApiKey(prewarmModel);
+          } catch (_) {
+            // Cache stays empty; tick 1 will fail and the cron resolves
+            // recipe_failed with a useful error from the backend.
+          }
+        }
+      }
+      cronEngine.start({
+        surfaceId,
+        sessionKey,
+        refresh: refreshValidated,
+        seedBody: validation.spec.body,
+        seedItems: validation.spec.items
+          ? validation.spec.items.map((it) =>
+              typeof it === "string"
+                ? it
+                : (it && typeof it.label === "string"
+                    ? (typeof it.body === "string" ? { label: it.label, body: it.body } : { label: it.label })
+                    : ""),
+            )
+          : undefined,
+        onResolve: (cronOutcome) => {
+          // The cron-produced outcome (with ticks + lastBody) becomes the tool
+          // result. capturedCronOutcome lets the terminal-via-user path read
+          // the merged outcome. Only the cron's OWN terminal outcomes resolve
+          // the pending call here (recipe_failed / timeout / external stop);
+          // user-action results resolve via onGlassesUiResult above.
+          const capture = capturedCronOutcome.get(surfaceId);
+          if (capture) capture(cronOutcome);
+          if (isTerminalOutcome(cronOutcome)) {
+            // Settle the in-flight call; if none is pending (the surface is in
+            // visible_awaiting_agent after a nonterminal user action and the
+            // cron then hit its own terminal — recipe_failed / maxDuration
+            // timeout), QUEUE the terminal so the agent's next render's
+            // onReattached returns discarded_for_exit and tears the surface
+            // down. Without this fallback the dead-cron surface would persist.
+            // Symmetric with the onGlassesUiResult terminal path.
+            if (!surfaceStore.resolve(surfaceId, cronOutcome)) {
+              surfaceStore.queueEvent(surfaceId, cronOutcome);
+            }
+          }
+        },
+      });
+    }
+
+    // Bound the wait via the existing timeout knob — disabled if cron is
+    // active (cron has its own maxDurationMs cap and the user explicitly
+    // owns the surface lifetime through dismiss).
+    const timeoutMs = Number.isFinite(params.timeoutMs)
+      ? params.timeoutMs
+      : resolveHandlerTimeoutMs();
+    if (!refreshValidated && Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      const setTimeoutFn =
+        deps && typeof deps.setTimeout === "function" ? deps.setTimeout : setTimeout;
+      const clearTimeoutFn =
+        deps && typeof deps.clearTimeout === "function" ? deps.clearTimeout : clearTimeout;
+      const handle = setTimeoutFn(() => {
+        // Resolves only if the entry is still pending; surfaceStore.resolve is a
+        // no-op when the client already produced a real outcome. timeout is
+        // terminal, so it also moves the surface to `exiting`.
+        surfaceStore.resolve(surfaceId, { result: "timeout", timeout_ms: timeoutMs });
+      }, timeoutMs);
+      return promise.then((outcome) => {
+        clearTimeoutFn(handle);
+        return outcome;
+      });
+    }
+    // Decoupled lifecycle: the call resolves on the user's action (via
+    // onGlassesUiResult) or the cron's terminal outcome (via onResolve). A
+    // nonterminal selected/back resolves the call WITHOUT stopping the cron —
+    // the surface (and its cron) persists until a terminal or a drain. So the
+    // old "stop the cron after any resolved outcome" tail is gone.
+    return promise;
+  }
+
+  // Per-session last-seen depth, used only to distinguish push (depth up) from
+  // pop (depth down) on the client nav-event. The surfaceIds + pause/resume
+  // live in surfaceStore (the single source of truth) — there is NO second
+  // stack here. On push the parent cron was already paused by applyRender
+  // during the agent's push render, so push is idempotent here; on pop we drive
+  // surfaceStore.popBack, which stops the child cron and staleness-resumes the
+  // parent (Spike B: the plugin owns the resume target).
+  const navDepthBySession = new Map(); // sessionKey -> lastSeenDepth
+
+  function handleNavEvent(sessionKey, ev) {
+    const newDepth = Number.isFinite(ev.depth) ? Math.max(1, Math.floor(ev.depth)) : 1;
+    const lastDepth = navDepthBySession.get(sessionKey) || surfaceStore.stackDepth(sessionKey) || 1;
+    const storeDepthBefore = surfaceStore.stackDepth(sessionKey);
+    let popCount = 0;
+    let resumedParent = null;
+    if (newDepth < lastDepth) {
+      // Pop(s): the client popped locally. Reconcile the store to the reported
+      // depth — each popBack stops the child cron + resumes the new parent.
+      let guard = 0;
+      while (surfaceStore.stackDepth(sessionKey) > newDepth && guard < 64) {
+        resumedParent = surfaceStore.popBack(sessionKey);
+        popCount += 1;
+        guard += 1;
+      }
+    }
+    // Push (newDepth > lastDepth) is already reflected in the store by the
+    // agent's push render (applyRender), so it is intentionally a no-op here.
+    emitLifecycle("nav_reconcile", "debug", {
+      sessionKey,
+      evSurfaceId: ev.surfaceId,
+      evDepth: ev.depth,
+      newDepth,
+      lastDepth,
+      storeDepthBefore,
+      popCount,
+      resumedParent,
+    });
+    navDepthBySession.set(sessionKey, newDepth);
+  }
+
+  return {
+    runDynamicUi,
+    handleNavEvent,
+    drainSession(sessionKey, outcome) {
+      cronEngine.stopAllForSession(sessionKey, outcome);
+      // Resolve pending + delete entries FIRST (so pending calls settle with
+      // `outcome`), THEN clear the per-session stack. exit() deletes entries
+      // without resolving, so it must NOT run before the drain or the pending
+      // promises would hang.
+      const reaped = surfaceStore.drainSession(sessionKey, outcome);
+      surfaceStore.exit(sessionKey); // clear the stack (crons already stopped)
+      navDepthBySession.delete(sessionKey); // drop stale nav depth (stack is now 0)
+      return reaped;
+    },
+    drainAll(outcome) {
+      cronEngine.stopAll(outcome);
+      const reaped = surfaceStore.drainAll(outcome);
+      for (const sessionKey of surfaceStore.sessionKeys()) {
+        surfaceStore.exit(sessionKey);
+      }
+      navDepthBySession.clear();
+      return reaped;
+    },
+    isCronActive(surfaceId) {
+      return cronEngine.isActive(surfaceId);
+    },
+    isCronPaused(surfaceId) {
+      const st = cronEngine._debugState(surfaceId);
+      return !!(st && st.paused);
+    },
+    surfaceStackDepth(sessionKey) {
+      return surfaceStore.stackDepth(sessionKey);
+    },
+    sessionForSurface(surfaceId) {
+      return surfaceStore.sessionForSurface(surfaceId);
+    },
+  };
+}
+
+export const GLASSES_UI_TOOL_DESCRIPTION = [
+  "Render a dynamic interface on the user's Even G2 glasses HUD instead of",
+  "replying with text. Three surface kinds:",
+  "  text_surface              — one formatted read-only block (≤1000 chars).",
+  "  list_surface              — a short pickable list, label-only (≤20 × 64 chars).",
+  "  list_with_details_surface — a pickable list where each item also carries a",
+  "                              short detail body (≤200 chars) shown as the user",
+  "                              scrolls; use when options need a 1-2 sentence",
+  "                              compare-before-choosing detail.",
+  "The call blocks until the user selects, dismisses, or backs out. result is one",
+  "of: selected, back, dismissed, timeout, recipe_failed, glasses_disconnected.",
+  "",
+  "Optional params:",
+  "  refresh — make the surface self-update on a timer (e.g. live host stats via",
+  "            the built-in system-stats tier). The plugin runs a recipe and",
+  "            patches the surface in place until the user exits.",
+  "  update  — how this render relates to the current surface: \"patch\" (edit",
+  "            fields; cron keeps ticking), \"replace\" (default; swap content in",
+  "            place, no back-target), \"push\" (stack a child screen; the parent",
+  "            is retained and its cron pauses, resuming on back).",
+  "",
+  "Before authoring any refreshing/live surface, per-item detail list, or",
+  "multi-screen flow, load the \"glasses-ui\" skill — it is the authoring source",
+  "of truth: the capability-tier ladder (system-stats host metrics, http data),",
+  "picking the lowest tier, recipe recon, the patch/replace/push moves and",
+  "exit-to-chat policy, the {{path|filter}} template + per-item {label,body}",
+  "reference, and worked examples (including a live system-stats",
+  "list_with_details surface). Keep this description lean; depth lives in the skill.",
+].join("\n");
+
+// Shared per-session depth counter. OpenClaw loads the plugin's register(api)
+// in multiple isolated contexts (gateway startup, per-agent-run tool discovery)
+// and each call to registerGlassesUiTool would otherwise close over its own
+// Map. execute() runs in the per-run context's closure while api.on("agent_end",
+// ...) fires from an earlier global-context closure, so reset-on-end would miss
+// the live counter. Stashing the map on globalThis under a stable Symbol gives
+// every load context the same Map to read and mutate.
+const DEPTH_MAP_SYMBOL = Symbol.for("ocuclaw.glasses-ui.depthBySession");
+function getSharedDepthMap() {
+  let m = globalThis[DEPTH_MAP_SYMBOL];
+  if (!(m instanceof Map)) {
+    m = new Map();
+    globalThis[DEPTH_MAP_SYMBOL] = m;
+  }
+  return m;
+}
+
+export function registerGlassesUiTool(api, service) {
+  if (!api || typeof api.registerTool !== "function") {
+    throw new Error("registerGlassesUiTool requires api.registerTool");
+  }
+  if (!service) {
+    throw new Error("registerGlassesUiTool requires the OcuClaw relay service");
+  }
+
+  const depthBySession = getSharedDepthMap();
+
+  function nextDepth(sessionKey) {
+    const prev = depthBySession.get(sessionKey) || 0;
+    const next = prev + 1;
+    depthBySession.set(sessionKey, next);
+    return next;
+  }
+
+  function resetDepth(sessionKey) {
+    if (sessionKey) {
+      depthBySession.delete(sessionKey);
+    } else {
+      depthBySession.clear();
+    }
+  }
+
+  async function resolveLlmApiKey(modelRef) {
+    if (!modelRef) return "";
+    try {
+      if (
+        api.runtime &&
+        api.runtime.modelAuth &&
+        typeof api.runtime.modelAuth.getApiKeyForModel === "function"
+      ) {
+        const cfg = api.config;
+        const key = await api.runtime.modelAuth.getApiKeyForModel({ model: modelRef, cfg });
+        return typeof key === "string" ? key : "";
+      }
+    } catch (_) {
+      /* fall through */
+    }
+    return "";
+  }
+
+  // Inline resolution: the cron engine asks for the API key once per tick
+  // for the current model. We cache the last-resolved model→key pair across
+  // ticks since model rarely changes within a cron. runDynamicUi awaits
+  // prewarmLlmApiKey before starting the cron, so tick 1 sees the resolved
+  // key. resolveLlmApiKeySync is only called after the prewarm has populated
+  // the cache; if it ever runs uncached it returns "" and the backend
+  // reports a useful error (cron resolves recipe_failed via the breaker).
+  let lastModel = null;
+  let lastKey = "";
+  async function prewarmLlmApiKey(modelRef) {
+    if (!modelRef || modelRef === lastModel) return;
+    const key = await resolveLlmApiKey(modelRef);
+    lastModel = modelRef;
+    lastKey = key;
+  }
+  function resolveLlmApiKeySync(modelRef) {
+    if (modelRef === lastModel) return lastKey;
+    // Fallback: prewarm wasn't called (or model changed mid-cron). Kick
+    // off async resolution but return empty for this tick.
+    resolveLlmApiKey(modelRef).then((key) => {
+      lastModel = modelRef;
+      lastKey = key;
+    });
+    return "";
+  }
+
+  const handler = createGlassesUiToolHandler({
+    relay: {
+      sendGlassesUiRender: (msg) => service.sendGlassesUiRender(msg),
+      sendGlassesUiSurfaceUpdate: (msg) => service.sendGlassesUiSurfaceUpdate(msg),
+      onGlassesUiResult: (cb) => service.onGlassesUiResult(cb),
+    },
+    emitLifecycle: (event, severity, data) => {
+      try {
+        if (service && typeof service.emitGlassesUiLifecycle === "function") {
+          service.emitGlassesUiLifecycle(event, severity, data);
+        }
+      } catch (_) {
+        // observability must never break the tool path
+      }
+    },
+    getGlassesUiLiveConfig: () => {
+      try {
+        const cfg = service.getRuntimeConfig && service.getRuntimeConfig();
+        return cfg && cfg.glassesUiLive ? cfg.glassesUiLive : { enabled: false };
+      } catch (_) {
+        return { enabled: false };
+      }
+    },
+    resolveLlmApiKey: resolveLlmApiKeySync,
+    prewarmLlmApiKey,
+    timeoutMs: () => {
+      // Live-read so config hot-reloads (`openclawctl config set …`) take
+      // effect on the next render without a gateway restart. A non-finite
+      // or <=0 value disables the timeout (infinite wait — the pre-2026-05-23
+      // behaviour, kept available as an escape hatch).
+      try {
+        const cfg = service.getRuntimeConfig && service.getRuntimeConfig();
+        const v = cfg && cfg.renderGlassesUiTimeoutMs;
+        return Number.isFinite(v) ? v : DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
+      } catch (_) {
+        return DEFAULT_RENDER_GLASSES_UI_TIMEOUT_MS;
+      }
+    },
+    isSessionConnected: () => {
+      // Consult the shared relay singleton (works across plugin-load
+      // contexts) for any connected downstream client. Per-session
+      // connection tracking would need deeper plumbing; the global check
+      // catches the common failure mode where the tool is invoked with no
+      // glasses client at all, which is what produced the indefinite hangs
+      // before this gate existed.
+      if (typeof service.hasConnectedAppClient === "function") {
+        return service.hasConnectedAppClient();
+      }
+      return false;
+    },
+    isUnderBackpressure: () => {
+      // The paint-floor coalescer sheds the trailing send while the relay/BLE
+      // send buffer is over its high-water mark (Spike D — there is no
+      // glass-side paint-ack, so transport pressure is the only signal). The
+      // signal source is relay-health-monitor's send-buffer high-water; until
+      // relay-service surfaces it as isGlassesSendBufferOverHighWater this
+      // returns false (safe default — no shedding). Completing this query is
+      // part of the BLE-backpressure hardening validated on hardware (Task 20).
+      try {
+        return typeof service.isGlassesSendBufferOverHighWater === "function"
+          ? service.isGlassesSendBufferOverHighWater()
+          : false;
+      } catch (_) {
+        return false;
+      }
+    },
+  });
+
+  // Wire glasses-disconnect to stop any active crons for the affected
+  // session. drainSession is also called by agent_end below; this path is
+  // distinct because a disconnect may happen mid-run without an agent_end.
+  if (typeof service.onAppClientDisconnect === "function") {
+    service.onAppClientDisconnect(({ sessionKey }) => {
+      const target = sessionKey || null;
+      if (target) {
+        handler.drainSession(target, { result: "glasses_disconnected" });
+      } else {
+        handler.drainAll({ result: "glasses_disconnected" });
+      }
+    });
+  }
+
+  // Reconcile client nav-events with the SINGLE store stack (Task 16). On pop
+  // the client reports the surfaceId now back on top + the post-pop depth; the
+  // store knows it. The relay frame carries no sessionKey, so resolve it from
+  // the surface's store entry (sessionForSurface), falling back to "main".
+  if (typeof service.onGlassesUiNavEvent === "function") {
+    service.onGlassesUiNavEvent((ev) => {
+      const sessionKey = handler.sessionForSurface(ev.surfaceId) || "main";
+      handler.handleNavEvent(sessionKey, ev);
+    });
+  }
+
+  function resolveDedicatedEvenAiSessionKey() {
+    try {
+      return service?.getRuntimeConfig?.()?.evenAiDedicatedSessionKey || null;
+    } catch (_) {
+      return null;
+    }
+  }
+
+  api.registerTool(
+    (ctx) => {
+      // Hide the tool from Even AI quick-action runs (dedicated or throwaway
+      // sessions). Those runs' responses go back to the Even Realities native
+      // app — not the OcuClaw chat surface — so a glasses popup wouldn't be
+      // reachable for the user. The tool stays visible to:
+      //   • the normal OcuClaw chat path (ocuclaw:<timestamp> sessions)
+      //   • the Even AI listen-mode path (which intercepts the HTTP
+      //     request and routes it through the active OcuClaw session, so
+      //     the sessionKey is an ocuclaw:<timestamp>, not ocuclaw:even-ai*).
+      const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : "";
+      if (isEvenAiAgentSession(sessionKey, resolveDedicatedEvenAiSessionKey())) {
+        return null;
+      }
+      const factorySessionKey = sessionKey || null;
+      return {
+        name: "render_glasses_ui",
+        description: GLASSES_UI_TOOL_DESCRIPTION,
+        parameters: glassesUiParametersSchema,
+        async execute(_toolCallId, params) {
+          const resolvedSessionKey = factorySessionKey || "main";
+          const depth = nextDepth(resolvedSessionKey);
+          try {
+            const outcome = await handler.runDynamicUi({
+              sessionKey: resolvedSessionKey,
+              depth,
+              spec: params,
+            });
+            return {
+              content: [{ type: "text", text: JSON.stringify(outcome) }],
+            };
+          } catch (err) {
+            const prev = depthBySession.get(resolvedSessionKey) || 0;
+            depthBySession.set(resolvedSessionKey, Math.max(0, prev - 1));
+            throw err;
+          }
+        },
+      };
+    },
+    { name: "render_glasses_ui" },
+  );
+
+  if (typeof api.on === "function") {
+    api.on("agent_end", (_event, ctx) => {
+      const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
+      // Drain any still-pending render for this session before clearing the
+      // depth counter. Normal-completion runs will have already resolved
+      // their tool call; this branch is the safety net for runs torn down
+      // externally (timeout, abort) so the in-memory map doesn't leak
+      // across runs.
+      if (sessionKey) {
+        handler.drainSession(sessionKey, { result: "preempted" });
+      }
+      resetDepth(sessionKey);
+    });
+  }
+
+  return function dispose() {
+    handler.drainAll({ result: "preempted" });
+    depthBySession.clear();
+  };
+}