ocuclaw 1.2.4 → 1.3.1

package/dist/tools/device-info-tool.js

@@ -0,0 +1,242 @@
+// OcuClaw plugin tool: surface G2 glasses battery to the agent over a
+// cross-process relay round-trip. Mirrors the render_glasses_ui pattern.
+// G2 only; anything else returns a structured device_unavailable error.
+
+import { randomUUID } from "node:crypto";
+
+export const deviceInfoParametersSchema = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+};
+
+export function validateDeviceInfoInput(input) {
+  if (input === undefined || input === null) return { ok: true };
+  if (typeof input !== "object" || Array.isArray(input)) {
+    return {
+      ok: false,
+      code: "invalid_input",
+      message: "input must be an object or undefined",
+    };
+  }
+  const keys = Object.keys(input);
+  if (keys.length > 0) {
+    return {
+      ok: false,
+      code: "invalid_input",
+      message: `unknown key(s): ${keys.join(", ")}`,
+    };
+  }
+  return { ok: true };
+}
+
+export function createPendingDeviceInfoMap() {
+  const byRequest = new Map(); // requestId -> { sessionKey, resolve }
+
+  function register(sessionKey, requestId) {
+    return new Promise((resolve) => {
+      byRequest.set(requestId, { sessionKey, resolve });
+    });
+  }
+
+  function resolve(requestId, outcome) {
+    const pending = byRequest.get(requestId);
+    if (!pending) return;
+    byRequest.delete(requestId);
+    pending.resolve(outcome);
+  }
+
+  function drainSession(sessionKey, outcome) {
+    const ids = [];
+    for (const [requestId, pending] of byRequest) {
+      if (pending.sessionKey === sessionKey) ids.push(requestId);
+    }
+    for (const requestId of ids) {
+      const pending = byRequest.get(requestId);
+      if (!pending) continue;
+      byRequest.delete(requestId);
+      pending.resolve(outcome);
+    }
+    return ids.length;
+  }
+
+  function drainAll(outcome) {
+    const ids = [...byRequest.keys()];
+    for (const requestId of ids) {
+      const pending = byRequest.get(requestId);
+      if (!pending) continue;
+      byRequest.delete(requestId);
+      pending.resolve(outcome);
+    }
+    return ids.length;
+  }
+
+  return { register, resolve, drainSession, drainAll };
+}
+
+// Default round-trip timeout. WebUI → bridge.getDeviceInfo() is a local
+// SDK call, so 10s is generous; experience may justify a config knob later.
+export const DEFAULT_DEVICE_INFO_TIMEOUT_MS = 10_000;
+
+export function createDeviceInfoToolHandler(deps) {
+  const pending = createPendingDeviceInfoMap();
+  const newRequestId =
+    deps && typeof deps.newRequestId === "function"
+      ? deps.newRequestId
+      : () => `dev-${randomUUID().slice(0, 8)}`;
+
+  function resolveHandlerTimeoutMs() {
+    if (!deps || deps.timeoutMs === undefined) return DEFAULT_DEVICE_INFO_TIMEOUT_MS;
+    if (typeof deps.timeoutMs === "function") {
+      const v = deps.timeoutMs();
+      return Number.isFinite(v) ? v : DEFAULT_DEVICE_INFO_TIMEOUT_MS;
+    }
+    return Number.isFinite(deps.timeoutMs) ? deps.timeoutMs : DEFAULT_DEVICE_INFO_TIMEOUT_MS;
+  }
+
+  deps.relay.onDeviceInfoResponse((msg) => {
+    if (!msg || typeof msg.requestId !== "string") return;
+    pending.resolve(msg.requestId, msg);
+  });
+
+  async function getDeviceInfo(params, ctx) {
+    const validation = validateDeviceInfoInput(params);
+    if (!validation.ok) {
+      const err = new Error(`${validation.code}: ${validation.message}`);
+      err.code = validation.code;
+      throw err;
+    }
+    const sessionKey =
+      ctx && typeof ctx.sessionKey === "string" && ctx.sessionKey.trim()
+        ? ctx.sessionKey.trim()
+        : "main";
+    if (typeof deps.isSessionConnected === "function" && !deps.isSessionConnected(sessionKey)) {
+      const err = new Error(
+        "glasses_not_connected: no Even Realities device client connected for this session",
+      );
+      err.code = "glasses_not_connected";
+      throw err;
+    }
+    const requestId = newRequestId();
+    const promise = pending.register(sessionKey, requestId);
+    try {
+      deps.relay.sendDeviceInfoRequest({ sessionKey, requestId });
+    } catch (sendErr) {
+      // Don't leak the pending entry if the relay rejects the send (e.g.
+      // relay not started). Resolve as device_unavailable so the awaiter
+      // sees a structured failure rather than hanging.
+      pending.resolve(requestId, { ok: false, code: "device_unavailable", requestId });
+      const outcome = await promise;
+      const code =
+        outcome && typeof outcome.code === "string" ? outcome.code : "device_unavailable";
+      const err = new Error(`${code}: device info request failed`);
+      err.code = code;
+      throw err;
+    }
+
+    const timeoutMs = resolveHandlerTimeoutMs();
+    const setTimeoutFn =
+      deps && typeof deps.setTimeout === "function" ? deps.setTimeout : setTimeout;
+    const clearTimeoutFn =
+      deps && typeof deps.clearTimeout === "function" ? deps.clearTimeout : clearTimeout;
+    let timeoutHandle = null;
+    if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+      timeoutHandle = setTimeoutFn(() => {
+        pending.resolve(requestId, { ok: false, code: "device_info_timeout", requestId });
+      }, timeoutMs);
+    }
+
+    const outcome = await promise;
+    if (timeoutHandle !== null) clearTimeoutFn(timeoutHandle);
+    if (outcome && outcome.ok === true) {
+      if (!outcome.data || typeof outcome.data !== "object") {
+        // ok=true with no data violates the wire contract; treat as
+        // device_unavailable rather than returning {} which the agent
+        // would describe as a successful empty snapshot.
+        const err = new Error(
+          "device_unavailable: device info response was ok but carried no data",
+        );
+        err.code = "device_unavailable";
+        throw err;
+      }
+      return outcome.data;
+    }
+    const code =
+      outcome && typeof outcome.code === "string" ? outcome.code : "device_unavailable";
+    const err = new Error(`${code}: device info request failed`);
+    err.code = code;
+    throw err;
+  }
+
+  return {
+    getDeviceInfo,
+    drainSession(sessionKey, outcome) {
+      return pending.drainSession(sessionKey, outcome);
+    },
+    drainAll(outcome) {
+      return pending.drainAll(outcome);
+    },
+  };
+}
+
+const TOOL_DESCRIPTION = [
+  "Read the user's G2 glasses battery percentage. Returns { batteryLevel: <int 0-100> }.",
+  "Errors: glasses_not_connected (no Even Realities device connected),",
+  "device_info_timeout, device_unavailable (SDK could not read battery).",
+  "Call only when the user asks about glasses battery.",
+].join("\n");
+
+export function registerDeviceInfoTool(api, service) {
+  if (!api || typeof api.registerTool !== "function") {
+    throw new Error("registerDeviceInfoTool requires api.registerTool");
+  }
+  if (!service) {
+    throw new Error("registerDeviceInfoTool requires the OcuClaw relay service");
+  }
+
+  const handler = createDeviceInfoToolHandler({
+    relay: {
+      sendDeviceInfoRequest: (msg) => service.sendDeviceInfoRequest(msg),
+      onDeviceInfoResponse: (cb) => service.onDeviceInfoResponse(cb),
+    },
+    // Global "any app client connected" check; the sessionKey arg the handler
+    // passes is intentionally ignored. Per-session connectivity tracking would
+    // need deeper plumbing — same trade-off as glasses-ui-tool.ts:403-414.
+    isSessionConnected: (_sessionKey) => {
+      if (typeof service.hasConnectedAppClient === "function") {
+        return service.hasConnectedAppClient();
+      }
+      return false;
+    },
+  });
+
+  api.registerTool({
+    name: "get_evenrealities_device_info",
+    description: TOOL_DESCRIPTION,
+    parameters: deviceInfoParametersSchema,
+    async execute(_toolCallId, params) {
+      const data = await handler.getDeviceInfo(params, { sessionKey: "main" });
+      return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+      };
+    },
+  });
+
+  // Per-session drain on agent_end implements the spec's data-flow step 11:
+  // any in-flight device_info_request for an ending agent run resolves with
+  // a structured device_info_aborted rather than hanging until plugin stop.
+  // Mirrors the agent_end hook in glasses-ui-tool.ts.
+  if (typeof api.on === "function") {
+    api.on("agent_end", (_event, ctx) => {
+      const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
+      if (sessionKey) {
+        handler.drainSession(sessionKey, { ok: false, code: "device_info_aborted" });
+      }
+    });
+  }
+
+  // Plugin-stop catch-all that drains everything left over across sessions.
+  return function dispose() {
+    handler.drainAll({ ok: false, code: "device_info_aborted" });
+  };
+}

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

@@ -0,0 +1,427 @@
+// Per-surface live-refresh cron engine.
+//
+// Manages the smoke test + tick loop for one or more periodic glasses
+// surfaces. Each surface is identified by surfaceId and tied to a sessionKey.
+// The engine is single-process (in the OcuClaw plugin), holds an in-memory
+// map of active crons, and resolves each cron with an outcome object when
+// any exit condition fires.
+//
+// Tests inject `executeRecipe` and timer functions; production code wires
+// the real executors from glasses-ui-recipes.ts and global setTimeout.
+
+import { substituteTemplate } from "./glasses-ui-template.js";
+
+const DEFAULT_FAILURE_BODY_PREFIX = "⚠ Update failed: ";
+
+// Mirror GLASSES_UI_LIMITS so live patches respect the same caps as the initial
+// render. Caller-supplied glassesUiLimits dep overrides these defaults so the
+// tool can pass through whatever validateGlassesUiSpec uses without coupling.
+const DEFAULT_GLASSES_UI_LIMITS = {
+  bodyMax: 1000,
+  itemMax: 64,
+  detailBodyMax: 200,
+  maxItems: 20,
+};
+
+// Exponential backoff applied to the NEXT tick's delay after consecutive
+// failures, capped so a long-down dependency can't starve the schedule
+// forever. Base = the recipe interval; cap = 60s; doubles per consecutive
+// failure. A successful tick resets to the base interval. Does not change the
+// breaker count (maxConsecutiveFailures still governs terminal stop).
+const BACKOFF_CAP_MS = 60_000;
+
+export function createGlassesUiCronEngine(deps) {
+  const executeRecipe = deps.executeRecipe;
+  const sendSurfaceUpdate = deps.sendSurfaceUpdate;
+  const resolveLlmCtx = deps.resolveLlmCtx || (() => ({}));
+  const setTimeoutFn = deps.setTimeoutFn || setTimeout;
+  const clearTimeoutFn = deps.clearTimeoutFn || clearTimeout;
+  // Monotonic clock for staleness math (never wall-clock; a prior freeze bug
+  // came from mixing Date.now() with performance.now()). Defaults to
+  // performance.now() so production wiring is correct even if a caller forgets.
+  const monotonicNowMs =
+    typeof deps.monotonicNowMs === "function" ? deps.monotonicNowMs : () => performance.now();
+  const limits = deps.glassesUiLimits && typeof deps.glassesUiLimits === "object"
+    ? { ...DEFAULT_GLASSES_UI_LIMITS, ...deps.glassesUiLimits }
+    : DEFAULT_GLASSES_UI_LIMITS;
+  // Permanent glasses.lifecycle observability (cron pause/resume/tick). No-op
+  // when the dep is absent (tests) or the debug category is disabled.
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
+
+  const active = new Map(); // surfaceId -> state
+
+  function emitSurfaceUpdate(state, patch) {
+    try {
+      sendSurfaceUpdate({ sessionKey: state.sessionKey, surfaceId: state.surfaceId, patch });
+      emitLifecycle("cron_tick_emit", "debug", {
+        surfaceId: state.surfaceId,
+        sessionKey: state.sessionKey,
+        generationToken: state.generationToken,
+        paused: !!state.paused,
+      });
+    } catch (err) {
+      // A throwing relay (e.g. "ocuclaw relay not started") must not escape
+      // as an unhandled rejection — it would lock the surface until
+      // maxDurationMs (30min default). Record as a tick failure so the
+      // breaker / onError policy can decide what to do on the next tick.
+      state.tickFailed += 1;
+      state.lastFailureAt = Date.now();
+      state.failureReason = `relay send failed: ${err && err.message ? err.message : err}`;
+      state.consecutiveFailures += 1;
+    }
+  }
+
+  function makeOutcome(state, extra) {
+    const ticks = {
+      count: state.tickCount,
+      succeeded: state.tickSucceeded,
+      failed: state.tickFailed,
+      lastSuccessAt: state.lastSuccessAt,
+    };
+    if (state.tickFailed > 0) ticks.lastFailureAt = state.lastFailureAt;
+    const outcome = { ticks, lastBody: state.lastBody, lastItems: state.lastItems };
+    if (state.failureReason) outcome.failureReason = state.failureReason;
+    return Object.assign({}, outcome, extra);
+  }
+
+  function resolveAndClean(state, extra) {
+    if (state.resolved) return;
+    state.resolved = true;
+    if (state.nextTickTimer) clearTimeoutFn(state.nextTickTimer);
+    if (state.maxDurationTimer) clearTimeoutFn(state.maxDurationTimer);
+    state.nextTickTimer = null;
+    state.maxDurationTimer = null;
+    active.delete(state.surfaceId);
+    try {
+      state.onResolve(makeOutcome(state, extra));
+    } catch (_) {
+      // swallow — caller's resolve handler is theirs to keep safe
+    }
+  }
+
+  function wrapForTemplate(value) {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return { ...value, output: value };
+    }
+    return { output: value };
+  }
+
+  function substituteOneItemTemplate(tpl, dataForTemplate, opts) {
+    // Object template -> {label, body}; plain-string template -> string (label-only,
+    // backward compatible with list_surface). Caps: label/itemMax, body/detailBodyMax.
+    if (tpl && typeof tpl === "object" && !Array.isArray(tpl)) {
+      const labelRaw =
+        typeof tpl.label === "string" ? substituteTemplate(tpl.label, dataForTemplate, opts) : "";
+      const out = { label: typeof labelRaw === "string" ? labelRaw.slice(0, limits.itemMax) : "" };
+      if (typeof tpl.body === "string") {
+        const bodyRaw = substituteTemplate(tpl.body, dataForTemplate, opts);
+        const cap = limits.detailBodyMax || limits.itemMax;
+        out.body = typeof bodyRaw === "string" ? bodyRaw.slice(0, cap) : bodyRaw;
+      }
+      return out;
+    }
+    const it = substituteTemplate(tpl, dataForTemplate, opts);
+    return typeof it === "string" ? it.slice(0, limits.itemMax) : it;
+  }
+
+  function itemsEqual(prev, next) {
+    if (!Array.isArray(prev) || !Array.isArray(next) || prev.length !== next.length) return false;
+    for (let i = 0; i < prev.length; i += 1) {
+      const a = prev[i];
+      const b = next[i];
+      if (typeof a === "string" || typeof b === "string") {
+        if (a !== b) return false;
+      } else if (a && b && typeof a === "object" && typeof b === "object") {
+        if (a.label !== b.label || a.body !== b.body) return false;
+      } else {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  function substituteIntoTargets(targets, output, previousOutput) {
+    const opts =
+      previousOutput !== undefined ? { previous: wrapForTemplate(previousOutput) } : undefined;
+    const dataForTemplate = wrapForTemplate(output);
+    const result = {};
+    if (typeof targets.body === "string") {
+      const body = substituteTemplate(targets.body, dataForTemplate, opts);
+      // Clamp to the same caps the initial render uses, so a runaway recipe
+      // can't blast the relay or glasses with a multi-MB body per tick.
+      result.body = typeof body === "string" ? body.slice(0, limits.bodyMax) : body;
+    }
+    if (Array.isArray(targets.items)) {
+      // Slice BEFORE map — only the first maxItems survive, so substituting
+      // templates beyond that is pure waste. validateRefreshSpec already rejects
+      // over-long arrays; this is defense-in-depth. Each entry is a string template
+      // (label-only) or a {label, body} template object (list_with_details bodies).
+      result.items = targets.items
+        .slice(0, limits.maxItems)
+        .map((tpl) => substituteOneItemTemplate(tpl, dataForTemplate, opts));
+    }
+    return result;
+  }
+
+  async function runOneTick(state) {
+    if (state.resolved) return;
+    state.lastTickAt = monotonicNowMs();
+    const tickGeneration = state.generationToken;
+    state.tickCount += 1;
+    let result;
+    try {
+      const ctx =
+        state.recipe.kind === "llm" ? resolveLlmCtx(state) : null;
+      result = await executeRecipe(state.recipe, ctx);
+    } catch (err) {
+      result = { error: `recipe threw: ${err && err.message ? err.message : err}` };
+    }
+
+    if (state.resolved) return;
+    // In-flight tick discard: if the surface was paused/popped/re-topped
+    // (generation bumped) while this recipe was running, drop its result so
+    // it can't patch a hidden screen. Stats already counted the attempt.
+    if (tickGeneration !== state.generationToken) {
+      return;
+    }
+
+    if (result && typeof result.error === "string") {
+      state.tickFailed += 1;
+      state.lastFailureAt = Date.now();
+      state.failureReason = result.error;
+      state.consecutiveFailures += 1;
+      state.pendingRetryAfterMs = Number.isFinite(result && result.retryAfterMs)
+        ? result.retryAfterMs
+        : null;
+
+      if (state.refresh.onError === "stop") {
+        resolveAndClean(state, { result: "recipe_failed" });
+        return;
+      }
+      if (state.consecutiveFailures >= state.refresh.maxConsecutiveFailures) {
+        resolveAndClean(state, { result: "recipe_failed" });
+        return;
+      }
+      if (state.refresh.onError === "show_error") {
+        const errorBody = DEFAULT_FAILURE_BODY_PREFIX + result.error.slice(0, 100);
+        if (state.lastBody !== errorBody) {
+          state.lastBody = errorBody;
+          emitSurfaceUpdate(state, { body: errorBody });
+        }
+      }
+      // keep_last: do nothing — preserve previous lastBody/lastItems.
+    } else if (result && Object.prototype.hasOwnProperty.call(result, "output")) {
+      state.tickSucceeded += 1;
+      state.lastSuccessAt = Date.now();
+      state.consecutiveFailures = 0;
+      state.failureReason = undefined;
+      state.pendingRetryAfterMs = null;
+      const substituted = substituteIntoTargets(state.refresh.targets, result.output, state.lastRecipeOutput);
+      state.lastRecipeOutput = result.output;
+      const patch = {};
+      let changed = false;
+      if (substituted.body !== undefined && substituted.body !== state.lastBody) {
+        patch.body = substituted.body;
+        state.lastBody = substituted.body;
+        changed = true;
+      }
+      if (substituted.items !== undefined) {
+        if (!itemsEqual(state.lastItems, substituted.items)) {
+          patch.items = substituted.items;
+          state.lastItems = substituted.items;
+          changed = true;
+        }
+      }
+      if (changed) {
+        emitSurfaceUpdate(state, patch);
+      }
+    } else {
+      state.tickFailed += 1;
+      state.failureReason = "recipe returned no output";
+      state.consecutiveFailures += 1;
+      if (state.consecutiveFailures >= state.refresh.maxConsecutiveFailures) {
+        resolveAndClean(state, { result: "recipe_failed" });
+        return;
+      }
+    }
+
+    // Schedule next tick. A run of failures backs off exponentially (capped);
+    // a Retry-After from the recipe (e.g. http 429) overrides the computed
+    // delay; a clean tick uses the base interval.
+    if (!state.resolved && !state.isSmokeTest && !state.paused) {
+      const base = state.refresh.intervalMs;
+      let delay = base;
+      if (state.consecutiveFailures > 0) {
+        delay = Math.min(base * Math.pow(2, state.consecutiveFailures), BACKOFF_CAP_MS);
+      }
+      if (Number.isFinite(state.pendingRetryAfterMs) && state.pendingRetryAfterMs > 0) {
+        delay = state.pendingRetryAfterMs;
+      }
+      state.nextTickTimer = setTimeoutFn(() => {
+        state.nextTickTimer = null;
+        runOneTick(state);
+      }, delay);
+    }
+  }
+
+  async function runSmokeTest(state) {
+    state.isSmokeTest = true;
+    await runOneTick(state);
+    state.isSmokeTest = false;
+    if (state.resolved) return; // smoke failed and policy was stop/breaker
+    // The smoke test must succeed before we begin the regular cadence — any
+    // failure on tick 1 short-circuits to recipe_failed regardless of policy.
+    if (state.tickFailed > 0) {
+      resolveAndClean(state, { result: "recipe_failed" });
+      return;
+    }
+    // After the smoke test, kick off the regular schedule.
+    state.nextTickTimer = setTimeoutFn(() => {
+      state.nextTickTimer = null;
+      runOneTick(state);
+    }, state.refresh.intervalMs);
+  }
+
+  return {
+    start(params) {
+      const state = {
+        surfaceId: params.surfaceId,
+        sessionKey: params.sessionKey,
+        refresh: params.refresh,
+        recipe: params.refresh.recipe,
+        onResolve: params.onResolve,
+        startedAt: Date.now(),
+        tickCount: 0,
+        tickSucceeded: 0,
+        tickFailed: 0,
+        consecutiveFailures: 0,
+        lastBody: params.seedBody,
+        lastItems: params.seedItems,
+        lastRecipeOutput: undefined,
+        lastSuccessAt: undefined,
+        lastFailureAt: undefined,
+        failureReason: undefined,
+        resolved: false,
+        nextTickTimer: null,
+        maxDurationTimer: null,
+        isSmokeTest: false,
+        lastTickAt: null,
+        generationToken: 0,
+        paused: false,
+        pendingRetryAfterMs: null,
+      };
+      active.set(state.surfaceId, state);
+      // Arm the duration cap.
+      state.maxDurationTimer = setTimeoutFn(() => {
+        resolveAndClean(state, { result: "timeout" });
+      }, params.refresh.maxDurationMs);
+      // start() is sync; runSmokeTest is async. Catch any rejection so it
+      // doesn't become an unhandled-rejection — instead resolve the cron
+      // with a recipe_failed outcome carrying the rejection message.
+      runSmokeTest(state).catch((err) => {
+        resolveAndClean(state, {
+          result: "recipe_failed",
+          failureReason: `smoke test threw: ${err && err.message ? err.message : err}`,
+        });
+      });
+    },
+    stop(surfaceId, outcome) {
+      const state = active.get(surfaceId);
+      if (!state) return false;
+      resolveAndClean(state, outcome || { result: "preempted" });
+      return true;
+    },
+    stopAllForSession(sessionKey, outcome) {
+      const matches = [];
+      for (const [sid, state] of active) {
+        if (state.sessionKey === sessionKey) matches.push(sid);
+      }
+      for (const sid of matches) this.stop(sid, outcome);
+      return matches.length;
+    },
+    stopAll(outcome) {
+      const ids = [...active.keys()];
+      for (const sid of ids) this.stop(sid, outcome);
+      return ids.length;
+    },
+    activeCount() {
+      return active.size;
+    },
+    isActive(surfaceId) {
+      return active.has(surfaceId);
+    },
+    _debugState(surfaceId) {
+      return active.get(surfaceId);
+    },
+    bumpGeneration(surfaceId) {
+      const state = active.get(surfaceId);
+      if (!state) return false;
+      state.generationToken += 1;
+      return true;
+    },
+    pause(surfaceId) {
+      const state = active.get(surfaceId);
+      if (!state || state.resolved) {
+        emitLifecycle("cron_pause", "debug", {
+          surfaceId,
+          found: !!state,
+          resolved: !!(state && state.resolved),
+        });
+        return false;
+      }
+      if (state.nextTickTimer) {
+        clearTimeoutFn(state.nextTickTimer);
+        state.nextTickTimer = null;
+      }
+      state.paused = true;
+      // Bump so an in-flight tick (started before pause) is discarded when it
+      // resolves — it must not patch the now-hidden parent screen.
+      state.generationToken += 1;
+      emitLifecycle("cron_pause", "debug", { surfaceId, found: true, resolved: false });
+      return true;
+    },
+    resume(surfaceId) {
+      const state = active.get(surfaceId);
+      if (!state || state.resolved) {
+        emitLifecycle("cron_resume", "debug", {
+          surfaceId,
+          found: !!state,
+          resolved: !!(state && state.resolved),
+          branch: "noop",
+        });
+        return false;
+      }
+      state.paused = false;
+      if (state.nextTickTimer) {
+        clearTimeoutFn(state.nextTickTimer);
+        state.nextTickTimer = null;
+      }
+      const lastTickAt = Number.isFinite(state.lastTickAt) ? state.lastTickAt : 0;
+      const elapsed = monotonicNowMs() - lastTickAt;
+      const intervalMs = state.refresh.intervalMs;
+      emitLifecycle("cron_resume", "debug", {
+        surfaceId,
+        found: true,
+        resolved: false,
+        elapsedMs: Math.round(elapsed),
+        intervalMs,
+        branch: elapsed >= intervalMs ? "refire" : "schedule",
+      });
+      if (elapsed >= intervalMs) {
+        // Stale: refire now via the TICK path (NOT runSmokeTest — a smoke
+        // failure is terminal regardless of onError policy). runOneTick
+        // re-arms the next tick itself.
+        runOneTick(state);
+      } else {
+        state.nextTickTimer = setTimeoutFn(() => {
+          state.nextTickTimer = null;
+          runOneTick(state);
+        }, intervalMs - elapsed);
+      }
+      return true;
+    },
+  };
+}
+
+export default { createGlassesUiCronEngine };