ocuclaw 1.2.4 → 1.3.1

package/dist/tools/session-title-tool.js

@@ -0,0 +1,209 @@
+export const SESSION_TITLE_LIMITS = {
+  titleMax: 55, // 64 SDK list-item cap minus ~9 chars headroom for "<time> - " prefix
+};
+
+export const sessionTitleParametersSchema = {
+  type: "object",
+  required: ["title"],
+  properties: {
+    title: {
+      type: "string",
+      minLength: 1,
+      maxLength: SESSION_TITLE_LIMITS.titleMax,
+    },
+  },
+  additionalProperties: false,
+};
+
+export function validateSessionTitleInput(input) {
+  if (!input || typeof input !== "object") {
+    return { ok: false, code: "missing_field", message: "input must be an object with a title field" };
+  }
+  if (!("title" in input)) {
+    return { ok: false, code: "missing_field", message: "title field is required" };
+  }
+  if (typeof input.title !== "string") {
+    return { ok: false, code: "invalid_type", message: "title must be a string" };
+  }
+  const trimmed = input.title.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, code: "title_empty", message: "title cannot be empty or whitespace-only" };
+  }
+  if (trimmed.length > SESSION_TITLE_LIMITS.titleMax) {
+    return {
+      ok: false,
+      code: "title_too_long",
+      message: `title is ${trimmed.length} chars; max ${SESSION_TITLE_LIMITS.titleMax}`,
+    };
+  }
+  return { ok: true, spec: { title: trimmed } };
+}
+
+const EVEN_AI_DEDICATED_KEY_PREFIX = "ocuclaw:even-ai";
+
+function isEvenAiDedicatedKey(sessionKey) {
+  if (typeof sessionKey !== "string") return false;
+  const normalized = sessionKey.trim().toLowerCase();
+  return (
+    normalized === EVEN_AI_DEDICATED_KEY_PREFIX ||
+    normalized.startsWith(`${EVEN_AI_DEDICATED_KEY_PREFIX}:`)
+  );
+}
+
+function gateReason(sessionKey, deps) {
+  if (typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey)) {
+    return "session_user_locked";
+  }
+  if (
+    typeof deps.isNeuralSessionNamesEnabled === "function" &&
+    !deps.isNeuralSessionNamesEnabled(sessionKey)
+  ) {
+    return "feature_disabled";
+  }
+  // Hard guard against the agent titling a session before the user has sent
+  // their first real message. The synthetic session-starter prompt the agent
+  // sees on /new + the proactive prompt-hook nudge can otherwise tempt the
+  // model into titling from a non-user input (observed: titles like "New
+  // session"). Real user sends are recorded via dispatchOcuClawUserSend ->
+  // sessionService.recordFirstSentUserMessage; the synthetic starter never is.
+  if (
+    typeof deps.hasRecordedUserMessage === "function" &&
+    !deps.hasRecordedUserMessage(sessionKey)
+  ) {
+    return "no_user_message_yet";
+  }
+  return null;
+}
+
+export function createSessionTitleToolHandler(deps) {
+  async function setSessionTitle(params) {
+    const validation = validateSessionTitleInput(params);
+    if (!validation.ok) {
+      const err = new Error(`${validation.code}: ${validation.message}`);
+      err.code = validation.code;
+      throw err;
+    }
+    const sessionKey = deps.peekSessionKey();
+    if (typeof sessionKey !== "string" || !sessionKey.trim()) {
+      const err = new Error(
+        "no_active_session: no OcuClaw session is currently active",
+      );
+      err.code = "no_active_session";
+      throw err;
+    }
+    if (isEvenAiDedicatedKey(sessionKey)) {
+      const err = new Error(
+        "session_not_renamable: the persistent EvenAI session cannot be retitled",
+      );
+      err.code = "session_not_renamable";
+      throw err;
+    }
+    const blockedReason = gateReason(sessionKey, deps);
+    if (blockedReason) {
+      const err = new Error(`${blockedReason}: tool unavailable for this session`);
+      err.code = blockedReason;
+      throw err;
+    }
+    const result = await deps.setSessionTitle(sessionKey, validation.spec.title);
+    if (result && result.ok === false) {
+      const err = new Error(`${result.code}: ${result.message || "set rejected"}`);
+      err.code = result.code;
+      throw err;
+    }
+    return result || { ok: true };
+  }
+  return { setSessionTitle };
+}
+
+const TOOL_DESCRIPTION = [
+  "Set a short title for the current chat session (shown in the user's glasses session list).",
+  "",
+  "When: first user turn that names any concrete topic — call eagerly. Later, only when the topic has clearly shifted. Skip greetings, acknowledgments, and no-topic messages.",
+  "",
+  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or surrounding quotes.",
+  "",
+  "Do not announce the rename unless the user explicitly asked to retitle.",
+].join("\n");
+
+export function createSessionTitlePromptHook(deps) {
+  return function sessionTitleBeforePromptBuild(_event, ctx) {
+    const sessionKey = ctx && typeof ctx.sessionKey === "string" ? ctx.sessionKey : null;
+    if (!sessionKey) return undefined;
+    const title = typeof deps.getSessionTitle === "function" ? deps.getSessionTitle(sessionKey) : null;
+    const userLocked =
+      typeof deps.isSessionUserLocked === "function" && deps.isSessionUserLocked(sessionKey);
+    const featureEnabled =
+      typeof deps.isNeuralSessionNamesEnabled === "function"
+        ? deps.isNeuralSessionNamesEnabled(sessionKey)
+        : true;
+
+    const fragments = [];
+    if (title) {
+      fragments.push(`Current session title: "${title}".`);
+    }
+    if (userLocked) {
+      fragments.push(
+        "The user has set a custom title; do not call set_session_title.",
+      );
+    } else if (!featureEnabled) {
+      fragments.push(
+        "Neural Topic Distiller is disabled; do not call set_session_title.",
+      );
+    } else if (title) {
+      fragments.push(
+        "Call set_session_title only if the topic has clearly shifted.",
+      );
+    } else {
+      const hasUserMessage =
+        typeof deps.hasRecordedUserMessage !== "function" ||
+        deps.hasRecordedUserMessage(sessionKey);
+      if (hasUserMessage) {
+        fragments.push(
+          "No session title is set yet. Call set_session_title now if the user's latest message names any concrete topic.",
+        );
+      }
+    }
+
+    if (fragments.length === 0) return undefined;
+    return { appendSystemContext: fragments.join(" ") };
+  };
+}
+
+export function registerSessionTitleTool(api, service) {
+  if (!api || typeof api.registerTool !== "function") {
+    throw new Error("registerSessionTitleTool requires api.registerTool");
+  }
+  if (!service) {
+    throw new Error("registerSessionTitleTool requires the OcuClaw relay service");
+  }
+
+  const handler = createSessionTitleToolHandler({
+    peekSessionKey: () => service.peekSessionKey(),
+    setSessionTitle: (sessionKey, title, opts) => service.setSessionTitle(sessionKey, title, opts),
+    isSessionUserLocked: (sessionKey) => service.isSessionUserLocked(sessionKey),
+    isNeuralSessionNamesEnabled: (sessionKey) => service.isNeuralSessionNamesEnabled(sessionKey),
+    hasRecordedUserMessage: (sessionKey) => service.hasRecordedUserMessage(sessionKey),
+  });
+
+  api.registerTool({
+    name: "set_session_title",
+    description: TOOL_DESCRIPTION,
+    parameters: sessionTitleParametersSchema,
+    async execute(_toolCallId, params) {
+      await handler.setSessionTitle(params);
+      return {
+        content: [{ type: "text", text: JSON.stringify({ status: "accepted" }) }],
+      };
+    },
+  });
+
+  if (typeof api.on === "function") {
+    const hook = createSessionTitlePromptHook({
+      getSessionTitle: (sessionKey) => service.getSessionTitle(sessionKey),
+      isSessionUserLocked: (sessionKey) => service.isSessionUserLocked(sessionKey),
+      isNeuralSessionNamesEnabled: (sessionKey) => service.isNeuralSessionNamesEnabled(sessionKey),
+      hasRecordedUserMessage: (sessionKey) => service.hasRecordedUserMessage(sessionKey),
+    });
+    api.on("before_prompt_build", hook);
+  }
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const PLUGIN_VERSION = "1.3.1";
+export const REQUIRES_CLIENT_VERSION = "1.3.1";

package/openclaw.plugin.json

@@ -1,34 +1,144 @@
 {
   "id": "ocuclaw",
+  "activation": {
+    "onStartup": true
+  },
   "name": "OcuClaw",
-  "description": "OcuClaw for Even G2 smart glasses, powered by OpenClaw.",
+  "description": "OcuClaw for Even Realities G2 smart glasses.",
+  "contracts": {
+    "tools": [
+      "render_glasses_ui",
+      "set_session_title",
+      "get_evenrealities_device_info"
+    ]
+  },
+  "skills": ["skills/glasses-ui"],
+  "hooks": {
+    "allowConversationAccess": true
+  },
+  "uiHints": {
+    "relayToken": {
+      "label": "Relay token",
+      "help": "Shared secret. Must match the relay server token set in the OcuClaw app inside Even Hub.",
+      "placeholder": "user-defined password",
+      "sensitive": true
+    },
+    "sonioxApiKey": {
+      "label": "Soniox API key",
+      "help": "Optional. Enables Soniox speech-to-text for voice input.",
+      "sensitive": true
+    },
+    "evenAiEnabled": {
+      "label": "Enable Even AI",
+      "help": "Routes Even AI agent requests through OcuClaw. Requires evenAiToken when enabled."
+    },
+    "evenAiToken": {
+      "label": "Even AI token",
+      "help": "Shared secret. Must match the password set in the Even AI Agent Configure section of the Even Realities app. Required when evenAiEnabled is true.",
+      "placeholder": "user-defined password",
+      "sensitive": true
+    },
+    "evenAiSystemPrompt": {
+      "label": "Even AI system prompt",
+      "help": "Optional extra system prompt appended to Even AI runs only.",
+      "advanced": true
+    },
+    "evenAiRoutingMode": {
+      "label": "Even AI routing mode",
+      "help": "active = current session; background = dedicated background session; background_new = fresh background session per request.",
+      "advanced": true
+    },
+    "wsBind": {
+      "label": "WebSocket bind address",
+      "help": "Local interface the OcuClaw relay listens on.",
+      "advanced": true
+    },
+    "wsPort": {
+      "label": "WebSocket port",
+      "help": "Local port the OcuClaw relay listens on.",
+      "advanced": true
+    },
+    "sessionLimit": {
+      "label": "Concurrent session limit",
+      "help": "Maximum simultaneous client sessions accepted by the relay.",
+      "advanced": true
+    },
+    "debugPayloadMaxBytes": {
+      "label": "Debug payload size limit",
+      "help": "Maximum byte size for debug payloads recorded for debugctl.",
+      "advanced": true
+    },
+    "debugNoisyPolicies": {
+      "label": "Debug noise policies",
+      "help": "Per-channel filters that suppress or sample noisy debug events.",
+      "advanced": true
+    },
+    "externalDebugToolsEnabled": {
+      "label": "External debug tools",
+      "help": "Allow debugctl-style external tools to call debug-set, debug-dump, and remote-control.",
+      "advanced": true
+    },
+    "evenAiRequestTimeoutMs": {
+      "label": "Even AI request timeout (ms) (deprecated)",
+      "advanced": true
+    },
+    "evenAiMaxBodyBytes": {
+      "label": "Even AI max body size (bytes) (deprecated)",
+      "advanced": true
+    },
+    "evenAiDedupWindowMs": {
+      "label": "Even AI dedup window (ms) (deprecated)",
+      "advanced": true
+    },
+    "evenAiDedicatedSessionKey": {
+      "label": "Even AI dedicated session key (deprecated)",
+      "help": "Deprecated — scheduled for removal in a future release. Internal session key prefix for background routing. Must start with 'ocuclaw:'.",
+      "advanced": true
+    },
+    "renderGlassesUiTimeoutMs": {
+      "label": "render_glasses_ui timeout (ms)",
+      "help": "How long a render_glasses_ui call waits for a user pick before resolving with { result: \"timeout\" }. Bounds the orphan tool_use corruption window if the gateway dies mid-render. Default 1800000 (30 minutes). Set 0 to disable (infinite wait — pre-2026-05-23 behaviour).",
+      "advanced": true
+    },
+    "freshnessWindowMs": {
+      "label": "Activity summary freshness window",
+      "help": "Milliseconds an agent summary outranks a tool label (3000-8000).",
+      "advanced": true
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
+    "required": ["relayToken"],
     "properties": {
       "relayToken": {
         "type": "string",
-        "minLength": 1
+        "minLength": 1,
+        "description": "Shared secret matching the OcuClaw relay token in the Even Hub app. Required."
       },
       "wsBind": {
         "type": "string",
-        "default": "127.0.0.1"
+        "default": "127.0.0.1",
+        "description": "Local interface the relay WebSocket listens on."
       },
       "wsPort": {
         "type": "integer",
         "minimum": 1,
         "maximum": 65535,
-        "default": 9000
+        "default": 9000,
+        "description": "Local port the relay WebSocket listens on."
       },
       "sessionLimit": {
         "type": "integer",
         "minimum": 1,
-        "default": 10
+        "default": 10,
+        "description": "Maximum concurrent client sessions accepted by the relay."
       },
       "debugPayloadMaxBytes": {
         "type": "integer",
         "minimum": 1,
-        "default": 2048
+        "default": 2048,
+        "description": "Maximum byte size for individual debug payloads recorded for debugctl."
       },
       "debugNoisyPolicies": {
         "anyOf": [
@@ -41,7 +151,8 @@
           {
             "type": "null"
           }
-        ]
+        ],
+        "description": "Per-channel filters that suppress or sample noisy debug events."
       },
       "externalDebugToolsEnabled": {
         "type": "boolean",
@@ -49,14 +160,18 @@
         "description": "Allow debugctl-style external debug tools to use debug-set, debug-dump, and remote-control."
       },
       "sonioxApiKey": {
-        "type": "string"
+        "type": "string",
+        "description": "Optional Soniox API key. Enables Soniox speech-to-text for voice input."
       },
       "evenAiEnabled": {
         "type": "boolean",
-        "default": false
+        "default": false,
+        "description": "Route Even AI agent requests through OcuClaw. When true, evenAiToken is required."
       },
       "evenAiToken": {
-        "type": "string"
+        "type": "string",
+        "minLength": 1,
+        "description": "Shared secret matching the password set in the Even AI Agent Configure section of the Even Realities app. Required when evenAiEnabled is true."
       },
       "evenAiSystemPrompt": {
         "type": "string",
@@ -65,17 +180,23 @@
       "evenAiRequestTimeoutMs": {
         "type": "integer",
         "minimum": 1,
-        "default": 60000
+        "default": 60000,
+        "deprecated": true,
+        "description": "Deprecated — scheduled for removal in a future release. The built-in default is used when this key is absent. Timeout (ms) for Even AI upstream requests."
       },
       "evenAiMaxBodyBytes": {
         "type": "integer",
         "minimum": 1,
-        "default": 65536
+        "default": 65536,
+        "deprecated": true,
+        "description": "Deprecated — scheduled for removal in a future release. The built-in default is used when this key is absent. Maximum response body size (bytes) accepted from the Even AI upstream."
       },
       "evenAiDedupWindowMs": {
         "type": "integer",
         "minimum": 0,
-        "default": 500
+        "default": 500,
+        "deprecated": true,
+        "description": "Deprecated — scheduled for removal in a future release. The built-in default is used when this key is absent. Dedup window (ms) for collapsing repeated Even AI requests."
       },
       "evenAiRoutingMode": {
         "type": "string",
@@ -84,12 +205,39 @@
           "background",
           "background_new"
         ],
-        "default": "active"
+        "default": "active",
+        "description": "Even AI session routing: active uses the current session, background reuses a dedicated session, background_new starts a fresh session per request."
       },
       "evenAiDedicatedSessionKey": {
         "type": "string",
-        "default": "ocuclaw:even-ai"
+        "default": "ocuclaw:even-ai",
+        "deprecated": true,
+        "description": "Deprecated — scheduled for removal in a future release. The built-in default is used when this key is absent. Internal session key prefix for background Even AI routing. Must start with 'ocuclaw:'."
+      },
+      "renderGlassesUiTimeoutMs": {
+        "type": "integer",
+        "minimum": 0,
+        "default": 1800000,
+        "description": "How long render_glasses_ui waits for user interaction before resolving as { result: \"timeout\" }. Bounds the orphan tool_use corruption window if the gateway dies during a pending render. Default 1800000 (30 minutes). 0 disables the timeout (infinite wait)."
+      },
+      "freshnessWindowMs": {
+        "type": "integer",
+        "minimum": 3000,
+        "maximum": 8000,
+        "default": 5000,
+        "description": "How long (ms) a fresh agent summary stays preferred over a tool label in the glasses activity status. Clamped 3000-8000."
       }
+    },
+    "if": {
+      "properties": {
+        "evenAiEnabled": {
+          "const": true
+        }
+      },
+      "required": ["evenAiEnabled"]
+    },
+    "then": {
+      "required": ["evenAiToken"]
     }
   }
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "ocuclaw",
-  "version": "1.2.4",
-  "description": "OcuClaw for Even G2 smart glasses, powered by OpenClaw.",
+  "version": "1.3.1",
+  "requiresClientVersion": "1.3.1",
+  "description": "OcuClaw for Even Realities G2 smart glasses.",
   "type": "module",
   "main": "./dist/index.js",
   "files": [
     "README.md",
     "dist/",
-    "openclaw.plugin.json"
+    "openclaw.plugin.json",
+    "skills/"
   ],
   "keywords": [
     "even",
@@ -24,13 +26,20 @@
   "openclaw": {
     "extensions": [
       "./dist/index.js"
-    ]
+    ],
+    "install": {
+      "npmSpec": "ocuclaw",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.5.20"
+    }
   },
   "dependencies": {
     "marked": "^17.0.2",
+    "undici": "^6.26.0",
     "ws": "^8.19.0"
   },
   "scripts": {
-    "build": "node ./scripts/build.mjs"
+    "build": "node ./scripts/build.mjs",
+    "prepare": "node ./scripts/build.mjs"
   }
 }

package/skills/glasses-ui/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: glasses-ui
+description: Authoring guide for render_glasses_ui surfaces on Even G2 glasses. Load BEFORE building any live/refreshing surface, per-item detail list, or multi-screen flow — covers the capability-tier ladder (system-stats host metrics, http data), the patch/replace/push moves and exit-to-chat policy, recipe recon, per-item {label,body} templates, and worked examples.
+user-invocable: false
+---
+
+# Authoring glasses surfaces with `render_glasses_ui`
+
+`render_glasses_ui` paints an interactive surface on the user's Even G2 HUD instead of a text reply. The call blocks until the user selects, dismisses, or backs out. This skill is the source of truth for **authoring** surfaces; the tool description is deliberately lean.
+
+## Surface kinds
+
+| kind | use it for | caps |
+|---|---|---|
+| `text_surface` | one formatted read-only block | body ≤ 1000 chars; optional `title` ≤ 64 |
+| `list_surface` | a short pickable list, label-only | ≤ 20 items × ≤ 64 chars |
+| `list_with_details_surface` | a pickable list where each item carries a detail body shown as the user scrolls | label ≤ 64, body ≤ 200; total of all bodies ≤ 6144 |
+
+`list_with_details` items are `{ label, body }` objects (`label` required, `body` optional). A bare string is treated as a label-only item. Use it when each option needs a 1–2 sentence compare-before-choosing detail — all bodies ship in one call, so the user browses with zero round-trips.
+
+## Capability tiers — pick the lowest tier that answers the need
+
+The refresh recipe runs at a capability tier. **Always pick the lowest tier that answers the need.**
+
+- **L0 — `http` (data APIs).** In-process, SSRF-guarded fetch → template → surface. For pure data: scores, status APIs, quotes, weather. **Not currently enableable on this install:** `http` is gated by `glassesUiLive.httpEnabled`, and that opt-in isn't reachable yet (the plugin's config-schema omits the `glassesUiLive` block — tracked as a separate fix). Until that lands, an `http` refresh is **rejected (refresh disabled)** — do not author one expecting it to run. It is documented here so you know the tier exists and is the right pick once enabled.
+- **L0′ — `system-stats` (host metrics).** Built-in, in-process `node:os` reader (RAM/CPU/load). **No operator gate** — governed only by the master `glassesUiLive.enabled` (on by default). **This is the only refresh tier that runs without operator config today.** Reach for it for anything host-metric.
+- **Reasoning / judgment tier (`agent`, L1/L2) — designed, not yet available.** A future tier where a sandboxed subagent interprets a page or local files on a timer. It is design-gated (credential-isolation + containment spike) and **not built** — there is no `agent` recipe kind. For a surface that needs interpretation *right now*, render it **once from your own turn** (compose the content yourself, render a static `text_surface`/list). A *self-refreshing* reasoning surface needs an agent in the loop, which isn't wired yet; a live reasoning tier is coming.
+
+### `system-stats` output fields (the `{{path}}` sources)
+
+`memTotalMb`, `memUsedMb`, `memFreeMb`, `memUsedPct`, `cpuPct`, `loadAvg1`. Optional recipe param `sampleWindowMs` (50–1000, default 200) sizes the CPU-sample window.
+
+## The four moves
+
+`render_glasses_ui` takes an optional `update` telling it how this render relates to the current surface. **Default is `replace`.**
+
+| move | what it does | when |
+|---|---|---|
+| `patch` | edit *some fields* of the current screen; the refresh cron **keeps ticking** | a partial in-place edit |
+| `replace` *(default)* | swap the *whole content* of the current screen in place; **no back-target** | new content, no going back |
+| `push` | stack a *new child screen*; the parent is retained and **its cron pauses** (resumes on Back) | new content, the user can go back |
+| exit to chat | *not a param* — just end your turn with a short text reply; the chat screen takes over and the surface disappears | you're done; respond in chat |
+
+**One-line rule:** partial edit → `patch`; new content, no going back → `replace`; new content, can go back → `push`; done → exit to chat.
+
+**Exit-to-chat policy:** on a *deliberate* exit (the user backs past the root, or you're finished), the default is to **respond in chat and not reflexively re-surface**. You retain the capability to surface again later in the conversation — just don't bounce a new surface up reflexively. On an *in-stack* Back (depth ≥ 2), the client transparently restores the parent and its cron resumes; you don't need to re-render it.
+
+> **Don't preempt yourself.** Omitting `update` means `replace` — it swaps your current surface in place. To drill into a detail *without losing the list*, use `push`. (Back restores the parent **surface** and re-fires its cron; it does not restore list scroll position.)
+
+## Live refresh: recipe recon (validate-then-commit)
+
+Add a `refresh` block to make a surface self-update: `{ recipe, intervalMs, targets, onError?, maxDurationMs?, maxConsecutiveFailures? }`. `intervalMs` ≥ 1000.
+
+When you submit a render carrying `refresh`, the plugin runs an **initial smoke-test tick before the surface commits**. If that tick fails, the call resolves with `result: "recipe_failed"` and a `failureReason` string — **read it, fix the recipe, and retry**; the surface and cron only start on success. This is your recon loop: don't guess twice, read the failure.
+
+`targets` maps recipe output → display:
+- `targets.body` — a string template for `text_surface`.
+- `targets.items` — an array of templates for list surfaces; each entry is either a string (label-only) or `{ label, body }`. The **whole array** is emitted each tick. **Labels are templated too**, so keep static labels as plain literals (no `{{…}}`) — only put `{{…}}` in the parts that should change.
+
+### Template filters
+
+`{{path}}` reads a value (`{{output}}` for the raw recipe output). Chain filters left-to-right:
+
+`trim` · `upper` · `lower` · `int` · `round:N` · `percent` (×100, append %) · `truncate:N` · `default:"--"` · `prefix:"+"` · `minus:previous.value` · `plus:previous.value`. Use `previous.*` paths for deltas vs the prior tick.
+
+## Worked examples
+
+### 1. Live host stats — `system-stats` text_surface (runs today)
+
+```js
+render_glasses_ui({
+  kind: "text_surface",
+  title: "Host",
+  body: "RAM —  CPU —",
+  refresh: {
+    recipe: { kind: "system-stats" },
+    intervalMs: 2000,
+    targets: { body: "RAM {{memUsedPct | round:0}}%  CPU {{cpuPct | round:0}}%  Load {{loadAvg1 | round:2}}" }
+  }
+})
+```
+
+### 2. Live host stats — `system-stats` list_with_details (the canonical interactive example, runs today)
+
+```js
+render_glasses_ui({
+  kind: "list_with_details_surface",
+  items: [
+    { label: "Memory", body: "—" },
+    { label: "CPU",    body: "—" },
+    { label: "Load",   body: "—" }
+  ],
+  refresh: {
+    recipe: { kind: "system-stats" },
+    intervalMs: 2000,
+    targets: {
+      items: [
+        { label: "Memory", body: "{{memUsedMb}} / {{memTotalMb}} MB ({{memUsedPct | round:0}}%)" },
+        { label: "CPU",    body: "{{cpuPct | round:1}}% busy" },
+        { label: "Load",   body: "{{loadAvg1 | round:2}} (1-min avg)" }
+      ]
+    }
+  }
+})
+// Labels are static literals (don't re-render); bodies tick every 2s.
+```
+
+### 3. `push` drill-down (don't preempt the list)
+
+```js
+// User highlights "Memory" and asks for detail → stack a child, keep the live list underneath.
+render_glasses_ui({
+  kind: "text_surface",
+  title: "Memory detail",
+  body: "Used … of … MB …",   // compose from what you know, or give the child its own system-stats refresh
+  update: "push"
+})
+// The parent list's cron pauses while the child is up; on Back it staleness-resumes.
+```
+
+### 4. `http` data (designed; NOT enableable on this install — shown for completeness)
+
+```js
+// L0 http — DATA APIs. Requires operator opt-in glassesUiLive.httpEnabled, which is
+// NOT currently reachable (config-schema gap). This will be REJECTED today — prefer system-stats.
+render_glasses_ui({
+  kind: "text_surface",
+  title: "AAPL",
+  body: "—",
+  refresh: {
+    recipe: { kind: "http", url: "https://api.example.com/quote/AAPL", jsonPath: "$.data" },
+    intervalMs: 30000,
+    targets: { body: "AAPL {{price}} ({{change | round:1 | prefix:\"+\"}})" }
+  }
+})
+```
+
+## Outcomes (the `result` you get back)
+
+| result | meaning |
+|---|---|
+| `selected` | user picked a list item; `selected_index` + `selected_text` returned |
+| `back` | user double-tapped above the root; they want to revise — re-render the previous step or pivot |
+| `dismissed` | dismissed at root, or no selection made |
+| `timeout` | no interaction within the window (non-refresh default 30 min; refresh ends at `maxDurationMs`) |
+| `recipe_failed` | refresh only — initial smoke tick failed, the consecutive-failure breaker fired, or `onError:stop`; `failureReason` carries the last error |
+| `glasses_disconnected` | refresh only — the glasses client dropped mid-cron |
+
+Refresh results also carry: `ticks: { count, succeeded, failed, lastSuccessAt, lastFailureAt? }`, `lastBody`, `lastItems`, and `failureReason` (on `recipe_failed`).
+
+## Quick reference
+
+- Pick the **lowest tier**: host metrics → `system-stats`; pure data API → `http` (not enabled yet). Needs interpretation → render once from your turn.
+- `update` default is `replace` (in-place). Use `push` to drill in without losing the parent; `patch` to edit fields while the cron keeps ticking.
+- `intervalMs` ≥ 1000. Read `failureReason` on `recipe_failed` and fix the recipe.
+- After a surface resolves, a short text reply exits to chat; another render replaces; silence lets it linger.