ocuclaw 1.3.0 → 1.3.2

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

@@ -51,21 +51,12 @@ function isEvenAiDedicatedKey(sessionKey) {
 }
 
 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.
+  // Explicit-rename-only: the Neural Session Names toggle governs AUTOMATIC
+  // titling (the distiller), not user-requested renames, so feature_disabled is
+  // gone. session_user_locked is gone too — a user who already named a session
+  // must be able to rename it again (the lock only blocks the distiller).
+  // The structural no_active_session / EvenAI-renamable guards live in the
+  // handler body. Only the no-user-message guard remains here.
   if (
     typeof deps.hasRecordedUserMessage === "function" &&
     !deps.hasRecordedUserMessage(sessionKey)
@@ -104,7 +95,9 @@ export function createSessionTitleToolHandler(deps) {
       err.code = blockedReason;
       throw err;
     }
-    const result = await deps.setSessionTitle(sessionKey, validation.spec.title);
+    const result = await deps.setSessionTitle(sessionKey, validation.spec.title, {
+      origin: "user_tool",
+    });
     if (result && result.ok === false) {
       const err = new Error(`${result.code}: ${result.message || "set rejected"}`);
       err.code = result.code;
@@ -115,60 +108,15 @@ export function createSessionTitleToolHandler(deps) {
   return { setSessionTitle };
 }
 
-const TOOL_DESCRIPTION = [
-  "Set a short title for the current chat session (shown in the user's glasses session list).",
+export const TOOL_DESCRIPTION = [
+  "Rename 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.",
+  "Call ONLY when the user explicitly asks to rename or retitle the session.",
+  "Automatic titling is handled elsewhere — do not call this proactively.",
   "",
-  "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.",
+  "Title: 2-5 word noun phrase, ≤55 chars, no trailing punctuation or quotes.",
 ].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");
@@ -196,14 +144,4 @@ export function registerSessionTitleTool(api, service) {
       };
     },
   });
-
-  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/tools/session-title-tool.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSessionTitleToolHandler, TOOL_DESCRIPTION } from "./session-title-tool.ts";
+
+function deps(over = {}) {
+  const calls = [];
+  return {
+    calls,
+    peekSessionKey: () => "ocuclaw:123",
+    setSessionTitle: (k, t, o) => { calls.push({ k, t, o }); return { ok: true }; },
+    ...over,
+  };
+}
+
+test("description is explicit-rename-only", () => {
+  assert.match(TOOL_DESCRIPTION, /explicitly asks to rename|user explicitly/i);
+});
+
+test("explicit rename passes origin user_tool", async () => {
+  const d = deps();
+  const h = createSessionTitleToolHandler(d);
+  await h.setSessionTitle({ title: "Trip Planning" });
+  assert.equal(d.calls[0].o.origin, "user_tool");
+});
+
+test("a user-locked session can STILL be renamed via the tool", async () => {
+  const d = deps({
+    setSessionTitle: (k, t, o) => {
+      // service-layer would allow user_tool over a lock; tool must not pre-block
+      return { ok: true };
+    },
+  });
+  const h = createSessionTitleToolHandler(d);
+  const r = await h.setSessionTitle({ title: "New Name" });
+  assert.deepEqual(r, { ok: true });
+});
+
+test("feature-disabled does NOT block an explicit rename", async () => {
+  const d = deps({ isNeuralSessionNamesEnabled: () => false });
+  const h = createSessionTitleToolHandler(d);
+  const r = await h.setSessionTitle({ title: "Anything" });
+  assert.deepEqual(r, { ok: true });
+});
+
+test("still rejects an empty title", async () => {
+  const h = createSessionTitleToolHandler(deps());
+  await assert.rejects(() => h.setSessionTitle({ title: "   " }), /title_empty/);
+});
+
+test("still rejects when no active session", async () => {
+  const h = createSessionTitleToolHandler(deps({ peekSessionKey: () => "" }));
+  await assert.rejects(() => h.setSessionTitle({ title: "X" }), /no_active_session/);
+});

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.2";
+export const REQUIRES_CLIENT_VERSION = "1.3.2";

package/openclaw.plugin.json

@@ -43,6 +43,11 @@
       "help": "Optional extra system prompt appended to Even AI runs only.",
       "advanced": true
     },
+    "sessionTitleModel": {
+      "label": "Session-title model",
+      "help": "Optional model override (\"provider/model\") for the background session-title distiller. Leave blank to use your normal model.",
+      "advanced": true
+    },
     "evenAiRoutingMode": {
       "label": "Even AI routing mode",
       "help": "active = current session; background = dedicated background session; background_new = fresh background session per request.",
@@ -226,6 +231,10 @@
         "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."
+      },
+      "sessionTitleModel": {
+        "type": "string",
+        "description": "Optional model override (\"provider/model\") for the background session-title distiller. When absent, the user's normal model is used."
       }
     },
     "if": {

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "ocuclaw",
-  "version": "1.3.0",
-  "requiresClientVersion": "1.3.0",
+  "version": "1.3.2",
+  "requiresClientVersion": "1.3.2",
   "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",
@@ -39,6 +40,7 @@
   },
   "scripts": {
     "build": "node ./scripts/build.mjs",
-    "prepare": "node ./scripts/build.mjs"
+    "prepare": "node ./scripts/build.mjs",
+    "test:unit": "node --import ./scripts/test-loader.mjs --test --test-force-exit \"src/**/*.test.ts\""
   }
 }

package/skills/glasses-ui/SKILL.md

@@ -0,0 +1,163 @@
+---
+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.
+
+## Before you author: is the tool loaded?
+
+`render_glasses_ui` is a plugin tool, and depending on the host runtime it may not sit in your initial tool list:
+
+1. **Not listed but searchable** — some runtimes (e.g. the Codex harness) defer OpenClaw dynamic tools behind tool search. Search your available/deferred tools for `render_glasses_ui` (it surfaces under the `openclaw` namespace), load it, and proceed.
+2. **Not findable at all** — the host's tool policy is filtering plugin tools. Newer OpenClaw versions (2026.6+) default `tools.profile` to `"coding"`, a base allowlist that strips plugin-owned tools; skills are not policy-filtered, which is why you can read this guide for a tool you cannot call. Don't improvise a workaround: tell the user to run `openclaw config set tools.alsoAllow '["ocuclaw"]' --strict-json` (merging `"ocuclaw"` into any existing `alsoAllow` list rather than overwriting) and restart the gateway, then try again.
+
+## 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.