ocuclaw 0.1.0 → 1.3.0

package/README.md

@@ -1,25 +1,80 @@
 # OcuClaw
 
-OcuClaw is an OpenClaw plugin for Even G2 smart glasses.
+OcuClaw is an OpenClaw plugin for Even G2 smart glasses. Use the OcuClaw application within Even Hub App Store to connect the client side.
+
+## Requirements
+
+OpenClaw `>= 2026.5.20` (older versions have a known plugin-install bug). Upgrade with `npm install -g openclaw@latest`.
 
 ## Install
 
+Install the plugin from the OpenClaw CLI:
+
 ```bash
 openclaw plugins install ocuclaw
-openclaw plugins enable ocuclaw
 ```
 
 ## Configure
 
-Set the relay token before starting or restarting the OpenClaw gateway:
+Required:
+
+Set the OcuClaw relay token. This is a user-created password that must match the relay server token field in the OcuClaw application within Even Hub App Store.
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.relayToken "your-relay-token"
+```
+
+Recommended:
+
+- `sonioxApiKey`: Enables Soniox speech-to-text for voice input.
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.sonioxApiKey "your-soniox-api-key"
+```
+
+- `evenAiEnabled`: Enables Even AI integration for OcuClaw.
+
+```bash
+openclaw config set plugins.entries.ocuclaw.config.evenAiEnabled true --strict-json
+```
+
+- `evenAiToken`: Sets the user-created password for Even AI requests. This must match the password set in the Even AI Agent Configure section within the Even Realities app.
 
 ```bash
-openclaw config set plugins.entries.ocuclaw.config.relayToken "<relay-token>"
+openclaw config set plugins.entries.ocuclaw.config.evenAiToken "your-even-ai-token"
 ```
 
-Optional settings live under `plugins.entries.ocuclaw.config.*`.
+> **Note:** When `evenAiEnabled` is `true`, `evenAiToken` is required. Config validation will reject the change if you enable Even AI without setting the token.
 
-## Notes
+Advanced optional settings:
 
-- Plugin id: `ocuclaw`
-- The WebUI is a separate artifact and is not bundled into this npm package.
+```bash
+openclaw config set plugins.entries.ocuclaw.config.wsBind "127.0.0.1"
+openclaw config set plugins.entries.ocuclaw.config.wsPort 9000 --strict-json
+openclaw config set plugins.entries.ocuclaw.config.sessionLimit 10 --strict-json
+openclaw config set plugins.entries.ocuclaw.config.externalDebugToolsEnabled true --strict-json
+```
+
+Run `openclaw plugins inspect ocuclaw` to see all settings with their descriptions and defaults.
+
+## Enable
+
+```bash
+openclaw plugins enable ocuclaw
+```
+
+## Restart
+
+Restart the gateway so the plugin and config changes take effect:
+
+```bash
+openclaw gateway restart
+```
+
+## Verify
+
+```bash
+openclaw plugins inspect ocuclaw --runtime
+openclaw plugins doctor
+openclaw gateway status
+```

package/dist/config/runtime-config.js

@@ -97,6 +97,56 @@ function resolveDebugNoisyPolicies(pluginValue, envValue) {
   return parseJsonOrUndefined(envValue, "debugNoisyPolicies");
 }
 
+// Supported live-refresh LLM backends. codex-cli was removed because the
+// Codex CLI's read-only sandbox still permits filesystem reads — agents
+// could exfil ~/.aws/credentials, ~/.ssh/*, etc. via stdout into the
+// glasses surface. Claude CLI is kept because --tools "" structurally
+// disables file access; operators who want Codex use openai-compat
+// pointed at the Codex API endpoint (tool-less).
+const GLASSES_UI_LIVE_BACKENDS = new Set([
+  "claude-cli",
+  "anthropic-api",
+  "openai-compat",
+]);
+
+const GLASSES_UI_LIVE_DEFAULT_MODEL = {
+  "claude-cli": "claude-haiku-4-5-20251001",
+  "anthropic-api": "anthropic/claude-haiku-4-5-20251001",
+  "openai-compat": "gpt-4o-mini",
+};
+
+function resolveGlassesUiLive(value) {
+  const raw = isObject(value) ? value : {};
+  const tickBackend = GLASSES_UI_LIVE_BACKENDS.has(raw.tickBackend)
+    ? raw.tickBackend
+    : "claude-cli";
+  const tickModel = pickString(raw.tickModel) || GLASSES_UI_LIVE_DEFAULT_MODEL[tickBackend];
+  const tickApiBaseUrl = pickString(raw.tickApiBaseUrl) || "https://api.openai.com";
+  return {
+    enabled: parseBool(raw.enabled, true),
+    tickBackend,
+    tickModel,
+    tickApiBaseUrl,
+    allowAgentModelOverride: parseBool(raw.allowAgentModelOverride, false),
+    tickMaxOutputTokens: parseIntOrDefault(raw.tickMaxOutputTokens, 200),
+    // Shell recipes run agent-supplied commands on a schedule as the plugin
+    // user. Default to disabled — operators must explicitly opt in via
+    // plugins.entries.ocuclaw.config.glassesUiLive.shellEnabled = true.
+    shellEnabled: parseBool(raw.shellEnabled, false),
+    // http recipes issue agent-influenced outbound network requests on a
+    // schedule. The recipe executor blocks loopback/RFC1918/link-local
+    // destinations and resolves hostnames through an SSRF-safe dispatcher,
+    // but the capability — "the plugin's gateway host can fetch arbitrary
+    // public URLs the agent chooses" — is itself worth an operator opt-in.
+    // Mirrors the shellEnabled default above; set
+    // plugins.entries.ocuclaw.config.glassesUiLive.httpEnabled = true to
+    // enable. The dispatcher protection still applies once enabled.
+    httpEnabled: parseBool(raw.httpEnabled, false),
+    llmEnabled: parseBool(raw.llmEnabled, true),
+    maxConcurrentSurfacesPerHost: parseIntOrDefault(raw.maxConcurrentSurfacesPerHost, 4),
+  };
+}
+
 export function createRuntimeConfig(opts = {}) {
   const pluginConfig = isObject(opts.pluginConfig) ? opts.pluginConfig : {};
   const openclawConfig = isObject(opts.openclawConfig) ? opts.openclawConfig : {};
@@ -106,7 +156,13 @@ export function createRuntimeConfig(opts = {}) {
 
   if (!relayToken) {
     throw new Error(
-      "OcuClaw relayToken is required. Set plugins.entries.ocuclaw.config.relayToken.",
+      [
+        "OcuClaw relayToken is required.",
+        "Set the plugin config with:",
+        '  openclaw config set plugins.entries.ocuclaw.config.relayToken "your-token"',
+        "The same token must be entered in the OcuClaw app's relay server token field within Even Hub.",
+        "Then restart the gateway: openclaw gateway restart",
+      ].join("\n"),
     );
   }
   if (!gatewayUrl) {
@@ -120,6 +176,22 @@ export function createRuntimeConfig(opts = {}) {
     );
   }
 
+  const evenAiEnabled = parseBool(pluginConfig.evenAiEnabled, false);
+  const evenAiToken = pickString(pluginConfig.evenAiToken);
+  if (evenAiEnabled && !evenAiToken) {
+    throw new Error(
+      [
+        "OcuClaw evenAiToken is required when evenAiEnabled is true.",
+        "Set the plugin config with:",
+        '  openclaw config set plugins.entries.ocuclaw.config.evenAiToken "your-token"',
+        "The same token must be entered as the password in the Even AI Agent Configure section of the Even Realities app.",
+        "To disable Even AI instead, run:",
+        "  openclaw config set plugins.entries.ocuclaw.config.evenAiEnabled false --strict-json",
+        "Then restart the gateway: openclaw gateway restart",
+      ].join("\n"),
+    );
+  }
+
   return {
     gatewayUrl,
     gatewayToken,
@@ -140,8 +212,8 @@ export function createRuntimeConfig(opts = {}) {
       pluginConfig.externalDebugToolsEnabled,
       false,
     ),
-    evenAiEnabled: parseBool(pluginConfig.evenAiEnabled, false),
-    evenAiToken: pickString(pluginConfig.evenAiToken),
+    evenAiEnabled,
+    evenAiToken,
     evenAiSystemPrompt: pickString(pluginConfig.evenAiSystemPrompt),
     evenAiRequestTimeoutMs: parseIntOrDefault(
       pluginConfig.evenAiRequestTimeoutMs,
@@ -159,6 +231,12 @@ export function createRuntimeConfig(opts = {}) {
     evenAiDedicatedSessionKey: parseEvenAiDedicatedSessionKey(
       pluginConfig.evenAiDedicatedSessionKey,
     ),
+    renderGlassesUiTimeoutMs: parseIntOrDefault(
+      pluginConfig.renderGlassesUiTimeoutMs,
+      30 * 60 * 1000,
+    ),
+    glassesUiLive: resolveGlassesUiLive(pluginConfig.glassesUiLive),
+    freshnessWindowMs: parseIntOrDefault(pluginConfig.freshnessWindowMs, 5000),
   };
 }