ocuclaw 1.3.0 → 1.3.1

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

@@ -1,53 +1,17 @@
-// Recipe executors for glasses_ui_refresh. Three kinds: shell (spawn bash),
-// http (in-process fetch), and llm (added in Task 3 — four backends behind
-// one dispatcher). All return either { output } or { error: <string> }.
+// Recipe executors for glasses_ui_refresh. Kinds: http (in-process fetch),
+// llm (two HTTP API backends behind one dispatcher), and system-stats
+// (in-process node:os reads). All return either { output } or
+// { error: <string> }. The shell (spawn bash) and llm claude-cli
+// (spawn claude) backends were removed to drop the plugin's last
+// child_process spawn — see the backends comment in config/runtime-config.ts.
 //
 // output is `string` for plain text and `object` for JSON. The cron engine
 // hands `output` to the template engine which handles both shapes.
 
-import { spawn } from "node:child_process";
-import { tmpdir, totalmem, freemem, loadavg, cpus } from "node:os";
+import { totalmem, freemem, loadavg, cpus } from "node:os";
 import * as dns from "node:dns";
 import { Agent } from "undici";
 
-// Env vars allowed to cross into the spawned Claude CLI subprocess.
-// Everything else is stripped — Claude reads its own auth from ~/.claude/
-// (reachable via HOME), so cloud-provider keys (AWS_*, GOOGLE_*,
-// ANTHROPIC_API_KEY, OPENAI_API_KEY, *_SECRET, *_TOKEN) and database URLs
-// must never reach the agent the CLI is running. Operators who want an
-// API key in the LLM-tick path use the *-api backends, which read the key
-// via the host's modelAuth resolver — not from spawn env.
-const CLI_SPAWN_ENV_ALLOWLIST = [
-  "PATH",
-  "HOME",
-  "USER",
-  "LOGNAME",
-  "SHELL",
-  "TERM",
-  "LANG",
-  "TZ",
-  "XDG_CONFIG_HOME",
-  "XDG_CACHE_HOME",
-  "XDG_DATA_HOME",
-  "XDG_RUNTIME_DIR",
-  "NODE_OPTIONS",
-];
-const CLI_SPAWN_ENV_ALLOWLIST_PREFIXES = ["LC_"];
-
-function buildScopedSpawnEnv() {
-  const sourceEnv = process.env || {};
-  const out = {};
-  for (const k of CLI_SPAWN_ENV_ALLOWLIST) {
-    if (typeof sourceEnv[k] === "string") out[k] = sourceEnv[k];
-  }
-  for (const k of Object.keys(sourceEnv)) {
-    if (CLI_SPAWN_ENV_ALLOWLIST_PREFIXES.some((p) => k.startsWith(p))) {
-      out[k] = sourceEnv[k];
-    }
-  }
-  return out;
-}
-
 const DEFAULT_TIMEOUT_MS = 10_000;
 const DEFAULT_OUTPUT_CAP_BYTES = 64 * 1024;
 
@@ -71,77 +35,6 @@ function parseJsonIfPossible(text) {
   }
 }
 
-export async function executeShellRecipe(params) {
-  const command = params && typeof params.command === "string" ? params.command : "";
-  if (!command) {
-    return { error: "shell recipe missing command" };
-  }
-  const timeoutMs = Number.isFinite(params && params.timeoutMs)
-    ? params.timeoutMs
-    : DEFAULT_TIMEOUT_MS;
-  const outputCapBytes = Number.isFinite(params && params.outputCapBytes)
-    ? params.outputCapBytes
-    : DEFAULT_OUTPUT_CAP_BYTES;
-
-  return new Promise((resolve) => {
-    const child = spawn("bash", ["-c", command], {
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    const chunks = [];
-    const errChunks = [];
-    let bytes = 0;
-    let truncated = false;
-    let done = false;
-
-    const finish = (result) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { child.kill("SIGKILL"); } catch (_) { /* already exited */ }
-      resolve(result);
-    };
-
-    const timer = setTimeout(() => {
-      finish({ error: `shell recipe timeout after ${timeoutMs}ms` });
-    }, timeoutMs);
-
-    child.stdout.on("data", (chunk) => {
-      if (bytes + chunk.length > outputCapBytes) {
-        const remaining = outputCapBytes - bytes;
-        if (remaining > 0) chunks.push(chunk.slice(0, remaining));
-        bytes = outputCapBytes;
-        truncated = true;
-        try { child.kill("SIGTERM"); } catch (_) {}
-      } else {
-        chunks.push(chunk);
-        bytes += chunk.length;
-      }
-    });
-
-    child.stderr.on("data", (chunk) => {
-      if (errChunks.length < 32) errChunks.push(chunk);
-    });
-
-    child.on("error", (err) => {
-      finish({ error: `shell recipe spawn error: ${err && err.message ? err.message : err}` });
-    });
-
-    child.on("close", (code, signal) => {
-      const stdout = Buffer.concat(chunks).toString("utf8");
-      if (code !== 0 && !truncated) {
-        const stderr = Buffer.concat(errChunks).toString("utf8").trim();
-        finish({
-          error: signal
-            ? `shell recipe killed by ${signal}`
-            : `shell recipe exit code ${code}${stderr ? ": " + stderr.slice(0, 200) : ""}`,
-        });
-        return;
-      }
-      finish({ output: parseJsonIfPossible(stdout) });
-    });
-  });
-}
-
 function checkIpv4Tuple(a, b) {
   if (a === 127) return "loopback IPv4 blocked";
   if (a === 10) return "RFC1918 IPv4 blocked";
@@ -504,67 +397,11 @@ function stripModelProviderPrefix(modelRef) {
   return idx === -1 ? modelRef : modelRef.slice(idx + 1);
 }
 
-async function runClaudeCli(params, deps) {
-  const spawnFn = deps && deps.spawn ? deps.spawn : spawn;
-  const promptText =
-    (params.systemPrompt ? params.systemPrompt + "\n\n" : "") + params.prompt;
-  const model = stripModelProviderPrefix(params.model);
-  // Lock the spawned Claude CLI to plan-mode with an empty toolset so the
-  // tick prompt can't drive file/shell/web tools to exfil. --bare disables
-  // hooks, plugin sync, CLAUDE.md auto-discovery, and keychain reads — the
-  // CLI runs as a pure text-in/text-out worker.
-  const args = [
-    "-p", promptText,
-    "--output-format", "text",
-    "--permission-mode", "plan",
-    "--tools", "",
-    "--bare",
-  ];
-  if (model) args.push("--model", model);
-  const timeoutMs = Number.isFinite(params.timeoutMs) ? params.timeoutMs : 60_000;
-
-  return new Promise((resolve) => {
-    const child = spawnFn("claude", args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      cwd: tmpdir(),
-      env: buildScopedSpawnEnv(),
-    });
-    const chunks = [];
-    const errChunks = [];
-    let done = false;
-    const finish = (result) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      try { child.kill && child.kill("SIGKILL"); } catch (_) {}
-      resolve(result);
-    };
-    const timer = setTimeout(
-      () => finish({ error: `claude-cli timeout after ${timeoutMs}ms` }),
-      timeoutMs,
-    );
-    child.stdout.on("data", (c) => chunks.push(c));
-    child.stderr.on("data", (c) => errChunks.push(c));
-    child.on("error", (err) => finish({ error: `claude-cli spawn error: ${err.message}` }));
-    child.on("close", (code) => {
-      if (code !== 0) {
-        const stderr = Buffer.concat(errChunks).toString("utf8").trim();
-        finish({ error: `claude-cli exit code ${code}${stderr ? ": " + stderr.slice(0, 200) : ""}` });
-        return;
-      }
-      finish({ output: Buffer.concat(chunks).toString("utf8") });
-    });
-  });
-}
-
-// codex-cli backend removed (round-5 autoreview): Codex's `read-only`
-// sandbox blocks writes and exec but still permits filesystem reads, so
-// an agent prompt could drive the spawned process to read ~/.aws/credentials,
-// ~/.ssh/*, etc. and emit them through stdout → glasses body. Claude CLI
-// is structurally safe because --tools "" disables every tool including
-// Read; Codex has no equivalent flag. Operators who want Codex point an
-// openai-compat backend at https://api.openai.com (or wherever Codex is
-// served) — that path has no tool surface at all.
+// Both CLI-spawn backends (codex-cli, claude-cli) were removed to eliminate
+// the plugin's last child_process spawn — see the backends comment in
+// config/runtime-config.ts for the rationale and the deferred native-delegation
+// track. Operators who want those providers point an *-api backend at the
+// provider endpoint (key resolved via the host modelAuth, tool-less).
 
 async function runAnthropicApi(params, deps) {
   const fetchFn = deps && deps.fetch ? deps.fetch : fetch;
@@ -666,8 +503,6 @@ export async function executeLlmRecipeWithDeps(recipe, ctx, deps) {
   };
   if (!baseParams.prompt) return { error: "llm recipe missing prompt" };
   switch (backend) {
-    case "claude-cli":
-      return runClaudeCli(baseParams, deps || {});
     case "anthropic-api":
       return runAnthropicApi(baseParams, deps || {});
     case "openai-compat":
@@ -743,4 +578,4 @@ export async function executeSystemStatsRecipe(params, opts) {
   }
 }
 
-export default { executeShellRecipe, executeHttpRecipe, executeLlmRecipe, executeLlmRecipeWithDeps, executeSystemStatsRecipe, computeCpuPct };
+export default { executeHttpRecipe, executeLlmRecipe, executeLlmRecipeWithDeps, executeSystemStatsRecipe, computeCpuPct };

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

@@ -7,7 +7,6 @@
 import { validateTemplate } from "./glasses-ui-template.js";
 import { createGlassesUiCronEngine } from "./glasses-ui-cron.js";
 import {
-  executeShellRecipe,
   executeHttpRecipe,
   executeLlmRecipe,
   executeSystemStatsRecipe,
@@ -32,7 +31,7 @@ import {
 export { createPendingRenderMap, createSurfaceStore, GLASSES_UI_LIMITS };
 
 export const GLASSES_UI_REFRESH_LIMITS = {
-  intervalMsMin: { shell: 1000, http: 1000, "system-stats": 1000, "llm-cli": 60_000, "llm-api": 30_000 },
+  intervalMsMin: { http: 1000, "system-stats": 1000, "llm-api": 30_000 },
   intervalMsMax: 3_600_000,
   maxDurationMsMin: 10_000,
   maxDurationMsMax: 7_200_000,
@@ -63,13 +62,6 @@ export const GLASSES_UI_REFRESH_LIMITS = {
 
 const ON_ERROR_VALUES = new Set(["keep_last", "show_error", "stop"]);
 
-function llmIntervalMinForBackend(backend) {
-  if (backend === "claude-cli") {
-    return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-cli"];
-  }
-  return GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-api"];
-}
-
 // The effective per-tick interval floor is the larger of the tier minimum and
 // the paint-floor coalescer's cadence (Spike D, 150ms) — no tick may schedule
 // faster than the glass can paint. Today every tier min already exceeds 150ms,
@@ -92,8 +84,8 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     return { ok: false, code: "refresh_invalid_recipe", message: "refresh.recipe is required" };
   }
   const kind = recipe.kind;
-  if (kind !== "shell" && kind !== "http" && kind !== "llm" && kind !== "system-stats") {
-    return { ok: false, code: "refresh_invalid_recipe", message: `recipe.kind must be shell/http/llm/system-stats, got ${JSON.stringify(kind)}` };
+  if (kind !== "http" && kind !== "llm" && kind !== "system-stats") {
+    return { ok: false, code: "refresh_invalid_recipe", message: `recipe.kind must be http/llm/system-stats, got ${JSON.stringify(kind)}` };
   }
   // Sanitize the recipe — clamp/reject agent-supplied timeoutMs / outputCapBytes
   // / maxOutputTokens to declared bounds, copy known fields only. The returned
@@ -105,23 +97,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     if (raw < min || raw > max) return undefined; // signal out-of-range
     return Math.floor(raw);
   };
-  if (kind === "shell") {
-    if (cfg.shellEnabled === false) return { ok: false, code: "refresh_disabled", message: "shell recipes disabled" };
-    if (typeof recipe.command !== "string" || !recipe.command.trim()) {
-      return { ok: false, code: "refresh_invalid_recipe", message: "shell recipe requires command (non-empty string)" };
-    }
-    sanitizedRecipe.command = recipe.command;
-    if (recipe.timeoutMs !== undefined) {
-      const v = bounded(recipe.timeoutMs, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin, GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax);
-      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.timeoutMs ${recipe.timeoutMs} out of bounds [${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMin}..${GLASSES_UI_REFRESH_LIMITS.shellHttpTimeoutMsMax}]` };
-      if (v !== null) sanitizedRecipe.timeoutMs = v;
-    }
-    if (recipe.outputCapBytes !== undefined) {
-      const v = bounded(recipe.outputCapBytes, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMin, GLASSES_UI_REFRESH_LIMITS.outputCapBytesMax);
-      if (v === undefined) return { ok: false, code: "refresh_invalid_recipe", message: `shell.outputCapBytes ${recipe.outputCapBytes} out of bounds` };
-      if (v !== null) sanitizedRecipe.outputCapBytes = v;
-    }
-  } else if (kind === "http") {
+  if (kind === "http") {
     if (cfg.httpEnabled === false) return { ok: false, code: "refresh_disabled", message: "http recipes disabled" };
     if (typeof recipe.url !== "string" || !recipe.url.trim()) {
       return { ok: false, code: "refresh_invalid_recipe", message: "http recipe requires url (non-empty string)" };
@@ -159,7 +135,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
     }
   } else if (kind === "system-stats") {
     // Built-in tier: host RAM/CPU via the in-process structured reader. NOT gated
-    // by httpEnabled/shellEnabled/llmEnabled — it touches no network, no shell, no
+    // by httpEnabled/llmEnabled — it touches no network, no shell, no
     // model. Only the master `enabled` switch (checked above) governs it. Do NOT
     // add a cfg.*Enabled gate here (intentional — Phase 3 design).
     if (recipe.sampleWindowMs !== undefined) {
@@ -176,7 +152,7 @@ export function validateRefreshSpec(refresh, glassesUiLiveCfg) {
   }
   const minForKind =
     kind === "llm"
-      ? llmIntervalMinForBackend(cfg.tickBackend)
+      ? GLASSES_UI_REFRESH_LIMITS.intervalMsMin["llm-api"]
       : GLASSES_UI_REFRESH_LIMITS.intervalMsMin[kind];
   const minEffective = effectiveIntervalFloorMs(minForKind);
   if (intervalMs < minEffective) {
@@ -307,16 +283,6 @@ const refreshSchemaForToolParams = {
     },
     recipe: {
       oneOf: [
-        {
-          type: "object",
-          required: ["kind", "command"],
-          properties: {
-            kind: { const: "shell" },
-            command: { type: "string" },
-            timeoutMs: { type: "integer" },
-            outputCapBytes: { type: "integer" },
-          },
-        },
         {
           type: "object",
           required: ["kind", "url"],
@@ -536,7 +502,6 @@ export function createGlassesUiToolHandler(deps) {
     emitLifecycle,
     monotonicNowMs: () => performance.now(),
     executeRecipe: async (recipe, ctx) => {
-      if (recipe.kind === "shell") return executeShellRecipe(recipe);
       if (recipe.kind === "http") return executeHttpRecipe(recipe);
       if (recipe.kind === "system-stats") return executeSystemStatsRecipe(recipe);
       if (recipe.kind === "llm") return executeLlmRecipe(recipe, ctx);
@@ -555,7 +520,7 @@ export function createGlassesUiToolHandler(deps) {
         ? Math.min(state.recipe.maxOutputTokens, cfg.tickMaxOutputTokens || 200)
         : (cfg.tickMaxOutputTokens || 200);
       return {
-        backend: cfg.tickBackend || "claude-cli",
+        backend: cfg.tickBackend || "anthropic-api",
         model,
         baseUrl: cfg.tickApiBaseUrl || "",
         apiKey: deps.resolveLlmApiKey ? deps.resolveLlmApiKey(model) : "",
@@ -697,10 +662,9 @@ export function createGlassesUiToolHandler(deps) {
     // content when this render carries a refresh.
     if (refreshValidated && !(update === "patch" && cronEngine.isActive(surfaceId))) {
       // Pre-warm the LLM API key cache so tick 1 doesn't see an empty key
-      // and fail the smoke test. For non-LLM recipes this is a no-op.
-      // For the claude-cli backend the resolved key is "" and not consumed
-      // (the CLI auths via its own login), so the prewarm is a harmless
-      // no-op there.
+      // and fail the smoke test. For non-LLM recipes this is a no-op. All llm
+      // backends are HTTP API backends that resolve a key via host modelAuth;
+      // a missing key degrades to a graceful recipe_failed on tick 1.
       if (refreshValidated.recipe.kind === "llm" && typeof deps.prewarmLlmApiKey === "function") {
         const cfg = deps.getGlassesUiLiveConfig ? deps.getGlassesUiLiveConfig() : {};
         const agentModel =

package/dist/version.js

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

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "ocuclaw",
-  "version": "1.3.0",
-  "requiresClientVersion": "1.3.0",
+  "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",

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.