ocuclaw 1.3.3 → 1.3.4

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

@@ -1,7 +1,3 @@
-// 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 = {
@@ -31,7 +27,7 @@ export function validateDeviceInfoInput(input) {
 }
 
 export function createPendingDeviceInfoMap() {
-  const byRequest = new Map(); // requestId -> { sessionKey, resolve }
+  const byRequest = new Map();
 
   function register(sessionKey, requestId) {
     return new Promise((resolve) => {
@@ -74,8 +70,6 @@ export function createPendingDeviceInfoMap() {
   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) {
@@ -122,9 +116,7 @@ export function createDeviceInfoToolHandler(deps) {
     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 =
@@ -150,9 +142,7 @@ export function createDeviceInfoToolHandler(deps) {
     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",
         );
@@ -199,9 +189,7 @@ export function registerDeviceInfoTool(api, service) {
       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();
@@ -222,10 +210,6 @@ export function registerDeviceInfoTool(api, service) {
     },
   });
 
-  // 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;
@@ -235,7 +219,6 @@ export function registerDeviceInfoTool(api, service) {
     });
   }
 
-  // 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

@@ -1,21 +1,7 @@
-// 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,
@@ -23,11 +9,6 @@ const DEFAULT_GLASSES_UI_LIMITS = {
   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) {
@@ -36,20 +17,17 @@ export function createGlassesUiCronEngine(deps) {
   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
+  const active = new Map();
 
   function emitSurfaceUpdate(state, patch) {
     try {
@@ -61,10 +39,7 @@ export function createGlassesUiCronEngine(deps) {
         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}`;
@@ -93,16 +68,12 @@ export function createGlassesUiCronEngine(deps) {
     state.nextTickTimer = null;
     state.maxDurationTimer = null;
     active.delete(state.surfaceId);
-    // silent: tear down timers/state WITHOUT firing onResolve. Used when the
-    // cron slot is being RECYCLED (a replace render swapping the surface's
-    // content in place) — a synthesized outcome here would reach
-    // surfaceStore.resolve with no pending call and LATCH a bogus exit that
-    // discards the very render doing the replacing (B7, found 2026-06-11).
+
     if (opts && opts.silent === true) return;
     try {
       state.onResolve(makeOutcome(state, extra));
     } catch (_) {
-      // swallow — caller's resolve handler is theirs to keep safe
+
     }
   }
 
@@ -114,8 +85,7 @@ export function createGlassesUiCronEngine(deps) {
   }
 
   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) : "";
@@ -154,15 +124,11 @@ export function createGlassesUiCronEngine(deps) {
     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));
@@ -185,9 +151,7 @@ export function createGlassesUiCronEngine(deps) {
     }
 
     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;
     }
@@ -216,7 +180,7 @@ export function createGlassesUiCronEngine(deps) {
           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();
@@ -252,9 +216,6 @@ export function createGlassesUiCronEngine(deps) {
       }
     }
 
-    // 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;
@@ -275,14 +236,13 @@ export function createGlassesUiCronEngine(deps) {
     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.resolved) return;
+
     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);
@@ -311,10 +271,7 @@ export function createGlassesUiCronEngine(deps) {
         resolved: false,
         nextTickTimer: null,
         maxDurationTimer: null,
-        // Pause-aware duration accounting (roadmap 6e): the cap measures
-        // ACTIVE time only. remainingMs is banked on pause and re-armed on
-        // resume; armedAtMs is monotonic (never wall-clock — the 2026-06-01
-        // freeze came from mixing clocks).
+
         maxDurationRemainingMs: params.refresh.maxDurationMs,
         maxDurationArmedAtMs: null,
         isSmokeTest: false,
@@ -324,20 +281,17 @@ export function createGlassesUiCronEngine(deps) {
         pendingRetryAfterMs: null,
       };
       active.set(state.surfaceId, state);
-      // Arm the duration cap.
+
       state.maxDurationArmedAtMs = monotonicNowMs();
       state.maxDurationTimer = setTimeoutFn(() => {
-        // Cron-death observability (Wave-1 e2e leg-4 gap): the cap firing was
-        // invisible — bounded tick-silence watches were the only evidence.
+
         emitLifecycle("cron_max_duration_reached", "debug", {
           surfaceId: state.surfaceId,
           sessionKey: state.sessionKey,
         });
         resolveAndClean(state, { result: "timeout" });
       }, params.refresh.maxDurationMs);
-      // start() is sync; runSmokeTest is async. Catch any rejection so it
-      // 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",
@@ -393,11 +347,7 @@ export function createGlassesUiCronEngine(deps) {
         clearTimeoutFn(state.nextTickTimer);
         state.nextTickTimer = null;
       }
-      // Pause-aware duration cap (roadmap 6e): stop the wall-clock burn and
-      // bank the remaining ACTIVE budget. Pre-6e the cap kept running while
-      // the parent hid under a pushed child — hardware-observed 2026-06-11
-      // as cron_resume {found:false} → Back landed on a frozen list. Guarded
-      // on the timer handle so a double-pause cannot double-deduct.
+
       if (state.maxDurationTimer) {
         clearTimeoutFn(state.maxDurationTimer);
         state.maxDurationTimer = null;
@@ -408,8 +358,7 @@ export function createGlassesUiCronEngine(deps) {
         state.maxDurationArmedAtMs = null;
       }
       state.paused = true;
-      // Bump so an in-flight tick (started before pause) is discarded when it
-      // resolves — it must not patch the now-hidden parent screen.
+
       state.generationToken += 1;
       emitLifecycle("cron_pause", "debug", { surfaceId, found: true, resolved: false });
       return true;
@@ -425,9 +374,7 @@ export function createGlassesUiCronEngine(deps) {
         });
         return false;
       }
-      // Re-arm the duration cap with the banked ACTIVE remainder (roadmap
-      // 6e). An exhausted budget resolves terminal timeout here instead of
-      // re-arming a dead cron — honest death beats a zombie surface.
+
       if (!state.maxDurationTimer) {
         if (state.maxDurationRemainingMs <= 0) {
           emitLifecycle("cron_resume", "debug", {
@@ -465,9 +412,7 @@ export function createGlassesUiCronEngine(deps) {
         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(() => {

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

@@ -1,26 +1,5 @@
-// Kind-descriptor registry for the glasses-UI surface kinds. Each descriptor
-// is a self-contained unit owning everything per-kind on the PLUGIN side:
-//   - schemaBranch:   the JSON-Schema oneOf entry for this kind
-//   - validateSpec:   per-kind validation, returns the canonical
-//                     { ok:true, spec } | { ok:false, code, message } shape
-//   - refreshTargets: which refresh.targets fields this kind binds
-//                     ("body" for text, "items" for the list kinds) —
-//                     informational in Phase 1, consumed in Phase 3.
-// The core (glassesUiParametersSchema, validateGlassesUiSpec) dispatches by
-// kind STRING through this registry and never switches on a specific kind, so
-// adding a kind is one descriptor with zero core edits (spec §Modularity).
-// Phase 1 ports the existing 3 kinds with NO behavior change.
-//
-// NOTE: this module imports GLASSES_UI_LIMITS from ./glasses-ui-limits.js (a
-// dependency-free leaf), NOT from ./glasses-ui-tool.js — glasses-ui-tool.js
-// imports THIS module, so importing back from it would form a require cycle
-// that the CJS emitter cannot resolve (module.exports is written at
-// end-of-module, so a mid-cycle require sees {}). See glasses-ui-limits.ts.
-
 import { GLASSES_UI_LIMITS } from "./glasses-ui-limits.js";
 
-// Shared title validation (moved from validateGlassesUiSpec — every kind ran
-// it before its branch). Returns an error result or null.
 function validateTitle(obj) {
   if (typeof obj.title === "undefined") return null;
   if (typeof obj.title !== "string") {
@@ -36,7 +15,6 @@ function validateTitle(obj) {
   return null;
 }
 
-// ---- text_surface ------------------------------------------------------
 const textSurfaceDescriptor = {
   kind: "text_surface",
   refreshTargets: ["body"],
@@ -48,7 +26,7 @@ const textSurfaceDescriptor = {
       kind: { const: "text_surface" },
       title: { type: "string", maxLength: GLASSES_UI_LIMITS.titleMax },
       body: { type: "string", maxLength: GLASSES_UI_LIMITS.bodyMax },
-      refresh: undefined, // filled by the tool when assembling the schema
+      refresh: undefined,
     },
   },
   validateSpec(obj) {
@@ -71,7 +49,6 @@ const textSurfaceDescriptor = {
   },
 };
 
-// ---- list_surface ------------------------------------------------------
 const listSurfaceDescriptor = {
   kind: "list_surface",
   refreshTargets: ["items"],
@@ -124,7 +101,6 @@ const listSurfaceDescriptor = {
   },
 };
 
-// ---- list_with_details_surface ----------------------------------------
 const listWithDetailsSurfaceDescriptor = {
   kind: "list_with_details_surface",
   refreshTargets: ["items"],
@@ -154,11 +130,7 @@ const listWithDetailsSurfaceDescriptor = {
   validateSpec(obj) {
     const titleErr = validateTitle(obj);
     if (titleErr) return titleErr;
-    // Empirically (2026-05-24 hardware logs), the agent often produces the
-    // parallel-array shape — items=[strings] plus a sibling `details` /
-    // `itemDetails` / `bodies` array — instead of the canonical [{label, body?}]
-    // objects. We accept the parallel-array shape and coerce it server-side so
-    // the wire format downstream stays canonical.
+
     const rawItems = obj.items;
     if (!Array.isArray(rawItems) || rawItems.length === 0) {
       return {
@@ -182,15 +154,14 @@ const listWithDetailsSurfaceDescriptor = {
     const items = rawItems.map((entry, i) => {
       if (typeof entry === "string") {
         const sibling = parallelBodies ? parallelBodies[i] : undefined;
-        // The sibling can be a plain string body, OR (some models do this) a
-        // {label, body} object that duplicates the label — accept either.
+
         if (typeof sibling === "string") {
           return { label: entry, body: sibling };
         }
         if (sibling && typeof sibling === "object" && typeof sibling.body === "string") {
           return { label: entry, body: sibling.body };
         }
-        // No matching parallel body — degrade gracefully to label-only.
+
         return { label: entry };
       }
       return entry;

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

@@ -1,16 +1,3 @@
-// Shared per-kind size caps for the glasses-UI surface tool. Extracted into its
-// own leaf module so BOTH the tool (glasses-ui-tool.ts) and the kind-descriptor
-// registry (glasses-ui-descriptors.ts) can import the same limits WITHOUT
-// forming an import cycle between those two modules.
-//
-// Why a leaf module is required (not a cycle): the plugin's CJS emitter
-// (scripts/build.mjs) converts `import {X} from "y"` into an in-place
-// `const {X} = require("y.cjs")` and appends `module.exports = {...}` only at
-// END of module execution (no live getters). Under those semantics a
-// bidirectional descriptors<->tool require resolves to `{}` mid-cycle and
-// crashes (GLASSES_UI_LIMITS undefined / listKindStrings not a function). Giving
-// the limits their own dependency-free module makes the graph a DAG
-// (tool -> {limits, descriptors}; descriptors -> limits), so no cycle exists.
 export const GLASSES_UI_LIMITS = {
   bodyMax: 1000,
   itemMax: 64,

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

@@ -1,22 +1,3 @@
-// Per-surface trailing-edge paint-floor coalescer.
-//
-// Governs ALL plugin->glass sends (initial RebuildPageContainer render and
-// every surface_update patch). Collapses bursts to last-write-wins per field
-// and emits at most one frame per paintFloorMs, with a leading-edge send + a
-// trailing send carrying the final merged patch.
-//
-// There is NO glass-side paint-ack: the only backpressure signal is
-// relay/BLE transport-side (see the isUnderBackpressure shed in Task 13).
-// Local fake-list textContainerUpgrade scroll-swaps are client-side and never
-// reach this coalescer.
-//
-// 250 is the unconditionally hardware-proven floor. Spike D approved lowering
-// to 150 ONLY once the backpressure shed has a live signal; the shed's
-// isGlassesSendBufferOverHighWater query is implemented nowhere yet, so the
-// shed is inert and 150 would run without its safety condition. Restore 150
-// when the relay-service bridge lands and is validated on hardware
-// (roadmap step 4, docs/superpowers/plans/2026-06-10-glasses-ui-state-reset-and-roadmap.md).
-
 export const DEFAULT_PAINT_FLOOR_MS = 250;
 
 export function createPaintFloorCoalescer(deps) {
@@ -28,7 +9,6 @@ export function createPaintFloorCoalescer(deps) {
   const isUnderBackpressure =
     typeof deps.isUnderBackpressure === "function" ? deps.isUnderBackpressure : () => false;
 
-  // surfaceId -> { sessionKey, lastSentAt, pendingPatch, timer }
   const bySurface = new Map();
 
   function isRenderSentinel(p) {
@@ -44,23 +24,12 @@ export function createPaintFloorCoalescer(deps) {
   }
 
   function mergePatch(base, incoming) {
-    // A render sentinel ({ __render, __depth, __spec }, Task 13) and a field
-    // patch ({ body }/{ items }/{ title }) must NEVER shallow-merge — a merged
-    // object would carry both __spec and a stray `body`, painting a malformed
-    // frame. They are different write kinds, so the LATER write supersedes the
-    // earlier one wholesale (a render replaces a queued field patch; a field
-    // patch after a queued render replaces that render). Same-kind writes
-    // merge last-write-wins per field as before.
-    //
-    // Marker-only field patch must NEVER drop a queued render (7a): merge the
-    // marker onto the render sentinel instead of superseding it wholesale.
+
     if (isMarkerOnly(incoming) && isRenderSentinel(base)) {
       return { ...base, __marker: incoming.marker };
     }
     if (isRenderSentinel(base) !== isRenderSentinel(incoming)) {
-      // Different write kinds: later supersedes wholesale (a render replaces a
-      // queued field patch; a content field patch replaces a queued render).
-      // Marker is sticky — carry it forward if the survivor didn't set one.
+
       const next = incoming && typeof incoming === "object" ? { ...incoming } : {};
       if (markerOf(next) === undefined) {
         const m = markerOf(base);
@@ -80,10 +49,7 @@ export function createPaintFloorCoalescer(deps) {
     if (!st || !st.pendingPatch) return;
     st.timer = null;
     if (isUnderBackpressure()) {
-      // Shed: do NOT send while the relay/BLE send buffer is over the high
-      // water mark. Retain pendingPatch (last-write-wins) and re-arm so the
-      // final merged value lands once pressure clears. No glass-side ack
-      // exists, so transport-side pressure is the only signal.
+
       st.timer = setTimeoutFn(() => flush(surfaceId), Math.max(16, paintFloorMs));
       return;
     }
@@ -103,12 +69,12 @@ export function createPaintFloorCoalescer(deps) {
     st.sessionKey = sessionKey;
     const elapsed = nowMs() - st.lastSentAt;
     if (elapsed >= paintFloorMs && !st.timer) {
-      // Leading edge: send immediately.
+
       st.lastSentAt = nowMs();
       send({ surfaceId, sessionKey, patch });
       return;
     }
-    // Within the floor: merge into the pending patch, arm a trailing flush.
+
     st.pendingPatch = mergePatch(st.pendingPatch, patch);
     if (!st.timer) {
       const wait = Math.max(0, paintFloorMs - elapsed);