ocuclaw 1.3.2 → 1.3.4

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

@@ -1,36 +1,87 @@
-// Per-session surface store for the glasses-UI tool. Extracted from
-// glasses-ui-tool.ts (Phase 1) so this stateful logic can be unit-tested in
-// isolation and so the tool file thins toward a schema+wiring layer (spec
-// §Lifecycle detail — Surface/stack lifecycle store).
-//
-// Phase 2 evolves the Phase-1 createPendingRenderMap IN PLACE into
-// createSurfaceStore (SINGLE store — there is never a second store alongside
-// it). The decoupled lifecycle means a surface's lifetime is independent of
-// any one tool call: resolve() settles the in-flight pending call but the
-// surface entry PERSISTS (keyed by surfaceId), and a new register() does NOT
-// preempt the previous surface. The legacy createPendingRenderMap name survives
-// only as an alias (bottom of this file) for the Phase 1 import path.
-
-// A terminal outcome ends the surface (teardown / exit). A nonterminal outcome
-// (selected/back) keeps the surface alive and hands the turn to the agent.
 const TERMINAL_RESULTS = new Set(["dismissed", "timeout", "glasses_disconnected", "preempted", "recipe_failed"]);
 
 export function isTerminalOutcome(outcome) {
   return !!(outcome && typeof outcome.result === "string" && TERMINAL_RESULTS.has(outcome.result));
 }
 
+export const GLASS_EVENT_ORIGINS = ["gesture", "schedule", "threshold", "system"];
+
+export function normalizeGlassesSessionKey(key) {
+  return typeof key === "string" ? key.replace(/^agent:[^:]+:/, "") : key;
+}
+
 export function createSurfaceStore(deps = {}) {
+
+  const storeId =
+    typeof deps.storeId === "string" && deps.storeId
+      ? deps.storeId
+      : `st-${Math.random().toString(36).slice(2, 8)}`;
+  const emitLifecycle =
+    typeof deps.emitLifecycle === "function" ? deps.emitLifecycle : () => {};
   const pauseCron = typeof deps.pauseCron === "function" ? deps.pauseCron : () => {};
   const resumeCron = typeof deps.resumeCron === "function" ? deps.resumeCron : () => {};
   const stopCron = typeof deps.stopCron === "function" ? deps.stopCron : () => {};
+  const now = typeof deps.now === "function" ? deps.now : Date.now;
   const mintSurfaceId =
     typeof deps.mintSurfaceId === "function"
       ? deps.mintSurfaceId
       : () => `ui-${Math.random().toString(36).slice(2, 10)}`;
-  // surfaceId -> { sessionKey, kind, pending: (resolver|null), lastContent,
-  //               state, queuedEvent, exitLatched }
+  const mintUuid =
+    typeof deps.mintUuid === "function"
+      ? deps.mintUuid
+      : () => `su-${Math.random().toString(36).slice(2, 10)}${Math.random().toString(36).slice(2, 6)}`;
+
   const bySurface = new Map();
-  const stackBySession = new Map(); // sessionKey -> [surfaceId, ...] (bottom→top)
+  const stackBySession = new Map();
+
+  const DEAD_LETTER_EVENT_CAP = 32;
+  const SURFACE_EVENT_LOG_CAP = 32;
+  const deadLetterBySession = new Map();
+  let eventSeq = 0;
+
+  function deadLetterFor(sessionKey) {
+    let list = deadLetterBySession.get(sessionKey);
+    if (!list) { list = []; deadLetterBySession.set(sessionKey, list); }
+    return list;
+  }
+
+  function deadLetterEntryEvents(sessionKey, surfaceId, entry, reason) {
+
+    if (!entry || entry.exitLatched || !entry.events || entry.events.length === 0) return;
+    const eventIds = entry.events.map((e) => e.eventId);
+    const list = deadLetterFor(sessionKey);
+    list.push({
+      surfaceUuid: entry.uuid,
+      surfaceId,
+      events: entry.events,
+      reason,
+      reapedAtMs: now(),
+
+      staleAfterMs: Number.isFinite(entry.staleAfterMs) ? entry.staleAfterMs : null,
+    });
+    entry.events = [];
+
+    emitLifecycle("dead_letter_appended", "debug", {
+      sessionKey,
+      surfaceId,
+      surfaceUuid: entry.uuid,
+      reason,
+      eventIds,
+      count: eventIds.length,
+    });
+    let total = list.reduce((n, r) => n + r.events.length, 0);
+    while (total > DEAD_LETTER_EVENT_CAP && list.length) {
+      const oldest = list[0];
+      const overflow = total - DEAD_LETTER_EVENT_CAP;
+      if (oldest.events.length <= overflow) {
+        total -= oldest.events.length;
+        list.shift();
+      } else {
+        oldest.events.splice(0, overflow);
+        total -= overflow;
+      }
+    }
+  }
 
   function stackFor(sessionKey) {
     let s = stackBySession.get(sessionKey);
@@ -38,55 +89,73 @@ export function createSurfaceStore(deps = {}) {
     return s;
   }
 
-  // A fresh entry starts un-latched with an empty queue. A `prior` entry (an
-  // in-place content swap of the SAME surfaceId — i.e. `replace`) carries its
-  // latched exit / last-wins queued event forward so reattach semantics are
-  // MOVE-INDEPENDENT: a terminal latched (or a nonterminal queued) during
-  // `visible_awaiting_agent` is honored on the agent's NEXT render whether that
-  // render is patch, replace (the schema DEFAULT) or push — never silently
-  // dropped by the rebuild. (Without this carry-forward, a `replace` rebuild
-  // would reset exitLatched=false / queuedEvent=null and onReattached would
-  // return "reattached" instead of "discarded_for_exit", failing to tear down.)
   function makeEntry(sessionKey, kind, prior) {
     return {
       sessionKey, kind: kind || null, pending: null, lastContent: null,
       state: "visible_pending",
       queuedEvent: prior ? prior.queuedEvent : null,
       exitLatched: prior ? !!prior.exitLatched : false,
+
+      uuid: prior ? prior.uuid : mintUuid(),
+      events: prior ? prior.events : [],
+      queueMode: prior && prior.queueMode === "log" ? "log" : "latest",
+
+      staleAfterMs: null,
+
+      title: prior ? prior.title : null,
+      awaitingAgentResponse: false,
     };
   }
 
-  function register(sessionKey, surfaceId, meta) {
+  function register(rawSessionKey, surfaceId, meta) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     return new Promise((resolve) => {
       const existing = bySurface.get(surfaceId);
       if (existing) {
-        // Re-attach to an existing surface: replace its pending resolver,
-        // keep the entry. No preempt of a different surface. Restore the
-        // pending state so a re-render returns to visible_pending before
-        // onReattached flushes any queued event / latched exit.
+
         existing.pending = resolve;
         if (meta && meta.kind) existing.kind = meta.kind;
+        if (meta && (meta.queueMode === "log" || meta.queueMode === "latest")) {
+          existing.queueMode = meta.queueMode;
+        }
+        existing.staleAfterMs = meta && Number.isFinite(meta.staleAfterMs) ? meta.staleAfterMs : null;
+        if (meta && typeof meta.title === "string") existing.title = meta.title;
+        existing.awaitingAgentResponse = false;
         existing.sessionKey = sessionKey;
         existing.state = "visible_pending";
         return;
       }
       const entry = makeEntry(sessionKey, meta && meta.kind ? meta.kind : null);
+      if (meta && (meta.queueMode === "log" || meta.queueMode === "latest")) {
+        entry.queueMode = meta.queueMode;
+      }
+      entry.staleAfterMs = meta && Number.isFinite(meta.staleAfterMs) ? meta.staleAfterMs : null;
+      if (meta && typeof meta.title === "string") entry.title = meta.title;
       entry.pending = resolve;
       bySurface.set(surfaceId, entry);
     });
   }
 
+  function decorateDelivery(entry, outcome) {
+    if (!outcome || typeof outcome !== "object" || Array.isArray(outcome)) return outcome;
+    if (outcome.surfaceUuid !== undefined) return outcome;
+    return { ...outcome, surfaceUuid: entry.uuid };
+  }
+
   function resolve(surfaceId, outcome) {
     const entry = bySurface.get(surfaceId);
     if (!entry || !entry.pending) return false;
     const pending = entry.pending;
-    entry.pending = null; // settle the call; surface entry persists
+    entry.pending = null;
     if (isTerminalOutcome(outcome)) {
       entry.state = "exiting";
+      entry.awaitingAgentResponse = false;
     } else {
       entry.state = "visible_awaiting_agent";
+
+      entry.awaitingAgentResponse = !!(outcome && outcome.result !== "window_expired");
     }
-    pending(outcome);
+    pending(decorateDelivery(entry, outcome));
     return true;
   }
 
@@ -99,18 +168,39 @@ export function createSurfaceStore(deps = {}) {
     return !!(entry && entry.pending);
   }
 
-  // Carried over from createPendingRenderMap (Phase 1). drainSession/drainAll
-  // resolve any in-flight pending call; Task 11 extends them to also stop
-  // crons and clear the per-session stack. They are the only resolve path that
-  // also DELETES surfaces (terminal teardown), unlike resolve() above.
-  function drainSession(sessionKey, outcome) {
+  function decorateDrainOutcome(entry, outcome) {
+    if (!outcome || typeof outcome !== "object" || Array.isArray(outcome)) return outcome;
+    return decorateDelivery(entry, {
+      ...outcome,
+      origin: typeof outcome.origin === "string" ? outcome.origin : "system",
+    });
+  }
+
+  function drainSession(rawSessionKey, outcome) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     let n = 0;
     for (const [surfaceId, entry] of [...bySurface]) {
       if (entry.sessionKey !== sessionKey) continue;
       const pending = entry.pending;
       entry.pending = null;
+      deadLetterEntryEvents(sessionKey, surfaceId, entry, "drain_session");
       bySurface.delete(surfaceId);
-      if (pending) { pending(outcome); n += 1; }
+      if (pending) { pending(decorateDrainOutcome(entry, outcome)); n += 1; }
+    }
+    return n;
+  }
+
+  function settlePending(rawSessionKey, outcome) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
+    let n = 0;
+    for (const [, entry] of bySurface) {
+      if (entry.sessionKey !== sessionKey || !entry.pending) continue;
+      const pending = entry.pending;
+      entry.pending = null;
+
+      entry.state = "visible_awaiting_agent";
+      pending(decorateDrainOutcome(entry, outcome));
+      n += 1;
     }
     return n;
   }
@@ -120,8 +210,9 @@ export function createSurfaceStore(deps = {}) {
     for (const [surfaceId, entry] of [...bySurface]) {
       const pending = entry.pending;
       entry.pending = null;
+      deadLetterEntryEvents(entry.sessionKey, surfaceId, entry, "drain_all");
       bySurface.delete(surfaceId);
-      if (pending) { pending(outcome); n += 1; }
+      if (pending) { pending(decorateDrainOutcome(entry, outcome)); n += 1; }
     }
     return n;
   }
@@ -131,16 +222,102 @@ export function createSurfaceStore(deps = {}) {
     return entry ? entry.state : null;
   }
 
-  function queueEvent(surfaceId, event) {
+  function queueEvent(surfaceId, event, opts) {
     const entry = bySurface.get(surfaceId);
     if (!entry) return false;
     if (isTerminalOutcome(event)) {
-      entry.exitLatched = true; // latched exit beats any queued nonterminal
+      entry.exitLatched = true;
       entry.queuedEvent = event;
-    } else if (!entry.exitLatched) {
-      entry.queuedEvent = event; // last-wins among nonterminals
+      return { ok: true, eventId: ++eventSeq, surfaceUuid: entry.uuid, kind: "terminal_latch" };
     }
-    return true;
+    if (entry.exitLatched) {
+
+      const latched = entry.queuedEvent;
+      const latchedOrigin = latched && typeof latched.origin === "string" ? latched.origin : "gesture";
+      if (latchedOrigin === "gesture") {
+
+        return false;
+      }
+      entry.exitLatched = false;
+      entry.queuedEvent = null;
+
+    }
+    const record = {
+      eventId: ++eventSeq,
+      surfaceUuid: entry.uuid,
+      origin: opts && typeof opts.origin === "string" ? opts.origin : "gesture",
+      actor: opts && typeof opts.actor === "string" ? opts.actor : "wearer",
+      queuedAtMs: now(),
+      deliveredVia: null,
+      outcome: event,
+    };
+    entry.events.push(record);
+    if (entry.events.length > SURFACE_EVENT_LOG_CAP) {
+      entry.events.splice(0, entry.events.length - SURFACE_EVENT_LOG_CAP);
+    }
+    entry.queuedEvent = event;
+    return { ok: true, eventId: record.eventId, surfaceUuid: entry.uuid };
+  }
+
+  function titleOf(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    return entry ? entry.title : null;
+  }
+
+  function markerFor(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    if (!entry) return null;
+    if (entry.pending) return "listening";
+    if ((entry.events && entry.events.length > 0) || entry.awaitingAgentResponse) return "inflight";
+    return "parked";
+  }
+
+  function clearAwaitingResponse(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
+    for (const [, entry] of bySurface) {
+      if (entry.sessionKey === sessionKey) entry.awaitingAgentResponse = false;
+    }
+  }
+
+  function breadcrumbFor(rawSessionKey) {
+    const s = stackBySession.get(normalizeGlassesSessionKey(rawSessionKey));
+    if (!s || s.length === 0) return null;
+    const titles = s
+      .map((id) => { const e = bySurface.get(id); return e && typeof e.title === "string" ? e.title : null; })
+      .filter((t) => typeof t === "string" && t.length > 0);
+    return titles.length ? titles.join(" › ") : null;
+  }
+
+  function uuidOf(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    return entry ? entry.uuid : null;
+  }
+
+  function peekEvents(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    return entry ? [...entry.events] : [];
+  }
+
+  function reduceForDelivery(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    if (!entry) return null;
+    if (entry.queueMode === "log") {
+      return { mode: "log", events: [...entry.events] };
+    }
+    const newest = entry.events.length ? entry.events[entry.events.length - 1] : null;
+    return { mode: "latest", outcome: newest ? newest.outcome : null };
+  }
+
+  function peekDeadLetter(sessionKey) {
+    const list = deadLetterBySession.get(normalizeGlassesSessionKey(sessionKey));
+    return list ? list.map((r) => ({ ...r, events: [...r.events] })) : [];
+  }
+
+  function drainDeadLetter(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
+    const list = deadLetterBySession.get(sessionKey) || [];
+    deadLetterBySession.set(sessionKey, []);
+    return list;
   }
 
   function isExitLatched(surfaceId) {
@@ -151,40 +328,70 @@ export function createSurfaceStore(deps = {}) {
   function onReattached(surfaceId) {
     const entry = bySurface.get(surfaceId);
     if (!entry) return "no_surface";
+    let staleLatchDropped = false;
     if (entry.exitLatched) {
-      // A terminal latched during the agent's turn. Discard this render and
-      // resolve the freshly-established pending call (the re-attach render's
-      // promise) with the latched terminal outcome so the tool call settles
-      // instead of hanging, then tear down.
-      entry.state = "exiting";
-      const terminal = entry.queuedEvent || { result: "dismissed" };
-      entry.queuedEvent = null;
-      if (entry.pending) {
-        const pending = entry.pending;
-        entry.pending = null;
-        pending(terminal);
+
+      const latched = entry.queuedEvent;
+      const latchedOrigin =
+        latched && typeof latched.origin === "string" ? latched.origin : "gesture";
+      if (latchedOrigin !== "gesture") {
+        entry.exitLatched = false;
+        entry.queuedEvent = null;
+        staleLatchDropped = true;
+      } else {
+
+        entry.state = "exiting";
+        const terminal = entry.queuedEvent || { result: "dismissed" };
+        entry.queuedEvent = null;
+        entry.events = [];
+        if (entry.pending) {
+          const pending = entry.pending;
+          entry.pending = null;
+          pending(decorateDelivery(entry, terminal));
+        }
+        return "discarded_for_exit";
       }
-      return "discarded_for_exit";
     }
     entry.state = "reattached";
-    const queued = entry.queuedEvent;
+
+    const newest = entry.events.length ? entry.events[entry.events.length - 1] : null;
+    let delivered = null;
+    if (newest) {
+      const parkedForMs = Math.max(0, now() - newest.queuedAtMs);
+      delivered = {
+        ...newest.outcome,
+        surfaceUuid: entry.uuid,
+        eventId: newest.eventId,
+        origin: newest.origin,
+        actor: newest.actor || "wearer",
+        queuedAtMs: newest.queuedAtMs,
+        parkedForMs,
+      };
+      if (Number.isFinite(entry.staleAfterMs) && parkedForMs > entry.staleAfterMs) {
+        delivered.stale = true;
+      }
+    } else if (entry.queuedEvent) {
+      delivered = decorateDelivery(entry, entry.queuedEvent);
+    }
     entry.queuedEvent = null;
-    if (queued && entry.pending) {
+    entry.events = [];
+    if (delivered && entry.pending) {
       const pending = entry.pending;
       entry.pending = null;
       entry.state = "visible_awaiting_agent";
-      pending(queued);
+      entry.awaitingAgentResponse = true;
+      pending(delivered);
     }
-    return "reattached";
+    return staleLatchDropped ? "reattached_stale_latch_dropped" : "reattached";
   }
 
   function topSurfaceId(sessionKey) {
-    const s = stackBySession.get(sessionKey);
+    const s = stackBySession.get(normalizeGlassesSessionKey(sessionKey));
     return s && s.length ? s[s.length - 1] : null;
   }
 
   function stackDepth(sessionKey) {
-    const s = stackBySession.get(sessionKey);
+    const s = stackBySession.get(normalizeGlassesSessionKey(sessionKey));
     return s ? s.length : 0;
   }
 
@@ -193,15 +400,11 @@ export function createSurfaceStore(deps = {}) {
     return entry ? entry.sessionKey : null;
   }
 
-  // Derive the target surfaceId from the session's current top. The agent
-  // never supplies a surfaceId (spec §Core model — the plugin owns them,
-  // keyed by session + stack). Returns { mode, surfaceId } so the caller can
-  // render against the bound id.
-  function applyRender(sessionKey, params) {
+  function applyRender(rawSessionKey, params) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     const stack = stackFor(sessionKey);
     const top = stack[stack.length - 1] || null;
-    // First render in a session (empty stack): create a root at depth 1,
-    // regardless of the requested update (there is nothing to patch/push onto).
+
     if (!top) {
       const id = mintSurfaceId();
       stack.push(id);
@@ -212,9 +415,7 @@ export function createSurfaceStore(deps = {}) {
       : params && params.update === "push" ? "push"
       : "replace";
     if (update === "patch") {
-      // Re-attach in place: reuse the top id, keep its entry + cron. The
-      // caller sends a field patch; the body content slot is updated by the
-      // render send, not here.
+
       const entry = bySurface.get(top);
       if (entry && params && params.kind) entry.kind = params.kind;
       if (entry) entry.state = "visible_pending";
@@ -227,39 +428,36 @@ export function createSurfaceStore(deps = {}) {
       bySurface.set(id, makeEntry(sessionKey, params && params.kind));
       return { mode: "push", surfaceId: id };
     }
-    // replace: swap the current top's CONTENT in place, reusing its id (no
-    // new back-target, depth unchanged). The entry is reset to a fresh
-    // pending state; the cron for this slot is reset for new content. CARRY
-    // FORWARD the prior entry's latched exit / queued event (same surfaceId)
-    // so a terminal/nonterminal recorded during visible_awaiting_agent is
-    // still honored by the subsequent onReattached — reattach semantics must
-    // be move-independent (replace, the schema DEFAULT, must behave like
-    // patch here, not silently drop a latched exit).
+
     const priorTop = bySurface.get(top);
-    // SILENT stop: this is slot recycling for the incoming replace render, not
-    // a real outcome. A non-silent stop fires the cron's onResolve with a
-    // synthesized `preempted`, which (with no pending call at this instant)
-    // latches a bogus exit onto the prior entry — carried into makeEntry below,
-    // it makes the very render we are applying discard-for-exit on re-attach
-    // ("fresh render instantly dismissed", B7 — the real B3 contamination
-    // mechanism, found 2026-06-11).
+
     stopCron(top, { silent: true });
     bySurface.set(top, makeEntry(sessionKey, params && params.kind, priorTop));
     return { mode: "replace", surfaceId: top };
   }
 
-  function popBack(sessionKey) {
+  function popBack(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     const stack = stackFor(sessionKey);
     const child = stack.pop();
-    if (child) { stopCron(child); bySurface.delete(child); }
+    if (child) {
+      stopCron(child);
+      deadLetterEntryEvents(sessionKey, child, bySurface.get(child), "pop_back");
+      bySurface.delete(child);
+    }
     const parent = stack[stack.length - 1] || null;
     if (parent) resumeCron(parent);
     return parent;
   }
 
-  function exit(sessionKey) {
+  function exit(rawSessionKey) {
+    const sessionKey = normalizeGlassesSessionKey(rawSessionKey);
     const stack = stackFor(sessionKey);
-    for (const id of stack) { stopCron(id); bySurface.delete(id); }
+    for (const id of stack) {
+      stopCron(id);
+      deadLetterEntryEvents(sessionKey, id, bySurface.get(id), "exit");
+      bySurface.delete(id);
+    }
     stackBySession.set(sessionKey, []);
     return true;
   }
@@ -269,17 +467,14 @@ export function createSurfaceStore(deps = {}) {
   }
 
   return {
-    register, resolve, hasSurface, isPending, drainSession, drainAll,
+    storeId,
+    register, resolve, hasSurface, isPending, drainSession, drainAll, settlePending,
     stateOf, queueEvent, isExitLatched, onReattached,
     applyRender, popBack, exit, topSurfaceId, stackDepth, sessionKeys, sessionForSurface,
+    uuidOf, titleOf, markerFor, clearAwaitingResponse, breadcrumbFor,
+    peekEvents, reduceForDelivery, peekDeadLetter, drainDeadLetter,
     _bySurface: bySurface,
   };
 }
 
-// Backwards-compatible alias. Phase 1 extracted createPendingRenderMap; Phase 2
-// evolved it into createSurfaceStore (single store — see the SINGLE-STORE
-// EVOLUTION note in the plan). The old name survives only as an alias so the
-// Phase 1 import path (glasses-ui-tool re-export) keeps resolving. There is
-// never a separate createPendingRenderMap *instance* — both names construct the
-// one evolved store.
 export const createPendingRenderMap = createSurfaceStore;

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

@@ -1,9 +1,3 @@
-// Template engine for glasses UI refresh recipes.
-// Pure functions. No I/O. Parses {{path | filter:arg | filter:arg}} expressions,
-// resolves paths against a data object (plus an optional previous-tick object
-// exposed under {{previous.*}}), and applies a small filter set sized exactly
-// to the spec's stated use cases.
-
 const KNOWN_FILTERS = new Set([
   "trim",
   "lower",
@@ -18,11 +12,10 @@ const KNOWN_FILTERS = new Set([
   "plus",
 ]);
 
-// Filters that require a numeric arg.
 const NUMERIC_ARG_FILTERS = new Set(["round", "truncate"]);
-// Filters that require a string arg (a quoted literal in the template).
+
 const STRING_ARG_FILTERS = new Set(["default", "prefix"]);
-// Filters that require a path arg (resolves against the data object).
+
 const PATH_ARG_FILTERS = new Set(["minus", "plus"]);
 
 function resolvePath(path, data, previous) {
@@ -51,10 +44,7 @@ function resolvePath(path, data, previous) {
 }
 
 function parseFilter(filterSrc) {
-  // Format: `name` or `name:arg` where arg can be:
-  //   - a quoted string: `default:"x"` or `prefix:"+"`
-  //   - a number: `round:2` or `truncate:18`
-  //   - a path: `minus:previous.value`
+
   const colonIdx = filterSrc.indexOf(":");
   const name = (colonIdx === -1 ? filterSrc : filterSrc.slice(0, colonIdx)).trim();
   const rawArg = colonIdx === -1 ? "" : filterSrc.slice(colonIdx + 1).trim();
@@ -81,7 +71,7 @@ function parseFilter(filterSrc) {
     }
     return { ok: true, name, arg: rawArg };
   }
-  // No-arg filters.
+
   return { ok: true, name, arg: null };
 }
 
@@ -113,10 +103,7 @@ function applyFilter(value, filter, data, previous) {
     case "default":
       return value === undefined || value === null || value === "" ? filter.arg : value;
     case "prefix": {
-      // Truthy = non-zero, non-empty. Numbers >= 0 with prefix:"+" should
-      // still prepend on positive values; here we treat "truthy" as the
-      // value's actual truthiness — agent uses prefix when they want the
-      // literal prepended on a non-empty value.
+
       if (value === undefined || value === null || value === "") return value;
       if (typeof value === "number" && value === 0) return value;
       return `${filter.arg}${value}`;
@@ -139,8 +126,6 @@ function stringify(value) {
   return String(value);
 }
 
-// PUBLIC ----
-
 export function substituteTemplate(template, data, opts) {
   if (typeof template !== "string") return "";
   const previous = opts && opts.previous ? opts.previous : null;
@@ -150,7 +135,7 @@ export function substituteTemplate(template, data, opts) {
     let value = resolvePath(path, data, previous);
     for (let i = 1; i < parts.length; i += 1) {
       const f = parseFilter(parts[i]);
-      if (!f.ok) return stringify(value); // shouldn't happen if validateTemplate was called
+      if (!f.ok) return stringify(value);
       value = applyFilter(value, f, data, previous);
     }
     return stringify(value);
@@ -161,7 +146,7 @@ export function validateTemplate(template) {
   if (typeof template !== "string") {
     return { ok: false, code: "refresh_template_invalid", message: "template must be a string" };
   }
-  // Detect unclosed braces.
+
   const openCount = (template.match(/\{\{/g) || []).length;
   const closeCount = (template.match(/\}\}/g) || []).length;
   if (openCount !== closeCount) {

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

@@ -7,10 +7,10 @@ test("description now carries the follow-up + back/selected usage rules", () =>
   assert.match(d, /text_surface/);
   assert.match(d, /list_surface/);
   assert.match(d, /list_with_details_surface/);
-  // Channel-3 additions (moved from the old nudge):
+
   assert.match(d, /NEXT output|next output/);
   assert.match(d, /back/i);
   assert.match(d, /selected/i);
-  // Skill pointer retained:
+
   assert.match(d, /glasses-ui/);
 });