ocuclaw 1.2.4 → 1.3.0

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

@@ -0,0 +1,278 @@
+// 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 function createSurfaceStore(deps = {}) {
+  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 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 bySurface = new Map();
+  const stackBySession = new Map(); // sessionKey -> [surfaceId, ...] (bottom→top)
+
+  function stackFor(sessionKey) {
+    let s = stackBySession.get(sessionKey);
+    if (!s) { s = []; stackBySession.set(sessionKey, s); }
+    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,
+    };
+  }
+
+  function register(sessionKey, surfaceId, meta) {
+    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;
+        existing.sessionKey = sessionKey;
+        existing.state = "visible_pending";
+        return;
+      }
+      const entry = makeEntry(sessionKey, meta && meta.kind ? meta.kind : null);
+      entry.pending = resolve;
+      bySurface.set(surfaceId, entry);
+    });
+  }
+
+  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
+    if (isTerminalOutcome(outcome)) {
+      entry.state = "exiting";
+    } else {
+      entry.state = "visible_awaiting_agent";
+    }
+    pending(outcome);
+    return true;
+  }
+
+  function hasSurface(surfaceId) {
+    return bySurface.has(surfaceId);
+  }
+
+  function isPending(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    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) {
+    let n = 0;
+    for (const [surfaceId, entry] of [...bySurface]) {
+      if (entry.sessionKey !== sessionKey) continue;
+      const pending = entry.pending;
+      entry.pending = null;
+      bySurface.delete(surfaceId);
+      if (pending) { pending(outcome); n += 1; }
+    }
+    return n;
+  }
+
+  function drainAll(outcome) {
+    let n = 0;
+    for (const [surfaceId, entry] of [...bySurface]) {
+      const pending = entry.pending;
+      entry.pending = null;
+      bySurface.delete(surfaceId);
+      if (pending) { pending(outcome); n += 1; }
+    }
+    return n;
+  }
+
+  function stateOf(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    return entry ? entry.state : null;
+  }
+
+  function queueEvent(surfaceId, event) {
+    const entry = bySurface.get(surfaceId);
+    if (!entry) return false;
+    if (isTerminalOutcome(event)) {
+      entry.exitLatched = true; // latched exit beats any queued nonterminal
+      entry.queuedEvent = event;
+    } else if (!entry.exitLatched) {
+      entry.queuedEvent = event; // last-wins among nonterminals
+    }
+    return true;
+  }
+
+  function isExitLatched(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    return !!(entry && entry.exitLatched);
+  }
+
+  function onReattached(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    if (!entry) return "no_surface";
+    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);
+      }
+      return "discarded_for_exit";
+    }
+    entry.state = "reattached";
+    const queued = entry.queuedEvent;
+    entry.queuedEvent = null;
+    if (queued && entry.pending) {
+      const pending = entry.pending;
+      entry.pending = null;
+      entry.state = "visible_awaiting_agent";
+      pending(queued);
+    }
+    return "reattached";
+  }
+
+  function topSurfaceId(sessionKey) {
+    const s = stackBySession.get(sessionKey);
+    return s && s.length ? s[s.length - 1] : null;
+  }
+
+  function stackDepth(sessionKey) {
+    const s = stackBySession.get(sessionKey);
+    return s ? s.length : 0;
+  }
+
+  function sessionForSurface(surfaceId) {
+    const entry = bySurface.get(surfaceId);
+    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) {
+    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);
+      bySurface.set(id, makeEntry(sessionKey, params && params.kind));
+      return { mode: "root", surfaceId: id };
+    }
+    const update = params && params.update === "patch" ? "patch"
+      : 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";
+      return { mode: "patch", surfaceId: top };
+    }
+    if (update === "push") {
+      pauseCron(top);
+      const id = mintSurfaceId();
+      stack.push(id);
+      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);
+    stopCron(top);
+    bySurface.set(top, makeEntry(sessionKey, params && params.kind, priorTop));
+    return { mode: "replace", surfaceId: top };
+  }
+
+  function popBack(sessionKey) {
+    const stack = stackFor(sessionKey);
+    const child = stack.pop();
+    if (child) { stopCron(child); bySurface.delete(child); }
+    const parent = stack[stack.length - 1] || null;
+    if (parent) resumeCron(parent);
+    return parent;
+  }
+
+  function exit(sessionKey) {
+    const stack = stackFor(sessionKey);
+    for (const id of stack) { stopCron(id); bySurface.delete(id); }
+    stackBySession.set(sessionKey, []);
+    return true;
+  }
+
+  function sessionKeys() {
+    return [...stackBySession.keys()];
+  }
+
+  return {
+    register, resolve, hasSurface, isPending, drainSession, drainAll,
+    stateOf, queueEvent, isExitLatched, onReattached,
+    applyRender, popBack, exit, topSurfaceId, stackDepth, sessionKeys, sessionForSurface,
+    _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

@@ -0,0 +1,182 @@
+// 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",
+  "upper",
+  "int",
+  "round",
+  "percent",
+  "truncate",
+  "default",
+  "prefix",
+  "minus",
+  "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) {
+  if (typeof path !== "string" || path === "") return undefined;
+  const segments = path.split(".");
+  let cursor;
+  if (segments[0] === "previous") {
+    cursor = previous;
+    segments.shift();
+  } else {
+    cursor = data;
+  }
+  for (const segment of segments) {
+    if (cursor === null || cursor === undefined) return undefined;
+    if (Array.isArray(cursor)) {
+      const idx = Number(segment);
+      if (!Number.isInteger(idx) || idx < 0 || idx >= cursor.length) return undefined;
+      cursor = cursor[idx];
+    } else if (typeof cursor === "object") {
+      cursor = cursor[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return cursor;
+}
+
+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();
+  if (!KNOWN_FILTERS.has(name)) {
+    return { ok: false, code: "refresh_template_invalid", message: `unknown filter: ${name}` };
+  }
+  if (NUMERIC_ARG_FILTERS.has(name)) {
+    const n = Number(rawArg);
+    if (rawArg === "" || !Number.isFinite(n)) {
+      return { ok: false, code: "refresh_template_invalid", message: `filter ${name} requires numeric arg, got: ${JSON.stringify(rawArg)}` };
+    }
+    return { ok: true, name, arg: n };
+  }
+  if (STRING_ARG_FILTERS.has(name)) {
+    const m = rawArg.match(/^"([^"]*)"$/);
+    if (!m) {
+      return { ok: false, code: "refresh_template_invalid", message: `filter ${name} requires quoted-string arg, got: ${JSON.stringify(rawArg)}` };
+    }
+    return { ok: true, name, arg: m[1] };
+  }
+  if (PATH_ARG_FILTERS.has(name)) {
+    if (!rawArg) {
+      return { ok: false, code: "refresh_template_invalid", message: `filter ${name} requires a path arg` };
+    }
+    return { ok: true, name, arg: rawArg };
+  }
+  // No-arg filters.
+  return { ok: true, name, arg: null };
+}
+
+function applyFilter(value, filter, data, previous) {
+  switch (filter.name) {
+    case "trim":
+      return typeof value === "string" ? value.trim() : value;
+    case "lower":
+      return typeof value === "string" ? value.toLowerCase() : value;
+    case "upper":
+      return typeof value === "string" ? value.toUpperCase() : value;
+    case "int": {
+      const n = Number(value);
+      return Number.isFinite(n) ? Math.trunc(n) : value;
+    }
+    case "round": {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return value;
+      const m = Math.pow(10, filter.arg);
+      return Math.round(n * m) / m;
+    }
+    case "percent": {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return value;
+      return `${Math.round(n * 1000) / 10}%`;
+    }
+    case "truncate":
+      return typeof value === "string" ? value.slice(0, filter.arg) : value;
+    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}`;
+    }
+    case "minus":
+    case "plus": {
+      const a = Number(value);
+      const b = Number(resolvePath(filter.arg, data, previous));
+      if (!Number.isFinite(a) || !Number.isFinite(b)) return value;
+      return filter.name === "minus" ? a - b : a + b;
+    }
+    default:
+      return value;
+  }
+}
+
+function stringify(value) {
+  if (value === undefined || value === null) return "";
+  if (typeof value === "string") return value;
+  return String(value);
+}
+
+// PUBLIC ----
+
+export function substituteTemplate(template, data, opts) {
+  if (typeof template !== "string") return "";
+  const previous = opts && opts.previous ? opts.previous : null;
+  return template.replace(/\{\{([^}]+)\}\}/g, (match, exprSrc) => {
+    const parts = exprSrc.split("|").map((s) => s.trim());
+    const path = parts[0];
+    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
+      value = applyFilter(value, f, data, previous);
+    }
+    return stringify(value);
+  });
+}
+
+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) {
+    return { ok: false, code: "refresh_template_invalid", message: "unmatched {{ or }} in template" };
+  }
+  const re = /\{\{([^}]+)\}\}/g;
+  let m;
+  while ((m = re.exec(template)) !== null) {
+    const parts = m[1].split("|").map((s) => s.trim());
+    for (let i = 1; i < parts.length; i += 1) {
+      const f = parseFilter(parts[i]);
+      if (!f.ok) return f;
+    }
+  }
+  return { ok: true };
+}
+
+export default { substituteTemplate, validateTemplate };