ocuclaw 0.1.0 → 1.3.0

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

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,7 +1,8 @@
 {
   "name": "ocuclaw",
-  "version": "0.1.0",
-  "description": "OcuClaw for Even G2 smart glasses, powered by OpenClaw.",
+  "version": "1.3.0",
+  "requiresClientVersion": "1.3.0",
+  "description": "OcuClaw for Even Realities G2 smart glasses.",
   "type": "module",
   "main": "./dist/index.js",
   "files": [
@@ -24,13 +25,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"
   }
 }