@vauxr/openclaw 2026.4.12-1 → 2026.5.31

package/README.md

@@ -59,7 +59,13 @@ These tools use the Vauxr REST API and work in any session, not just vauxr voice
 
 ## Installation
 
-Install from the repo directly:
+Install from ClawHub 🦞
+
+```bash
+openclaw plugins install clawhub:@vauxr/openclaw
+```
+
+Or install from the repo directly:
 
 ```bash
 openclaw plugins install path:/path/to/vauxr-openclaw
@@ -90,11 +96,32 @@ Then configure in your OpenClaw config:
 ```
 
 - `url` — Vauxr base URL (HTTP)
-- `token` — channel token generated in the Vauxr portal
+- `token` — channel token generated in the Vauxr web client
 - `voiceSystemPrompt` — optional, appended to the system prompt for all vauxr sessions
+- `alsoAllow` — optional, extra tools to grant vauxr-originated agent runs (see below)
+- `targetAgent` — required if `alsoAllow` is set; the id of the agent that handles vauxr sessions
 
 The `allowPromptInjection` hook permission is required for the voice system prompt to take effect.
 
+### Granting broader tools to vauxr sessions
+
+OpenClaw's runtime treats the internal `webchat` channel more permissively than third-party channels: tools like `gateway` and `nodes` are stripped from vauxr-originated runs even when the agent's profile would otherwise allow them. To restore those tools on vauxr sessions, set `alsoAllow` and `targetAgent`:
+
+```json
+{
+  "channels": {
+    "vauxr": {
+      "url": "http://vauxr:8765",
+      "token": "your-channel-token",
+      "alsoAllow": ["gateway", "nodes"],
+      "targetAgent": "nova-cloud"
+    }
+  }
+}
+```
+
+On configure, the plugin writes a `channel:vauxr:*` entry into `agents.list[id=targetAgent].tools.toolsBySender`. The expansion is scoped to vauxr-originated runs only — other channels are unaffected. Be deliberate about what you grant: `gateway` lets the model restart OpenClaw, `nodes` lets it invoke commands on connected hardware nodes.
+
 ---
 
 ## Usage
@@ -147,3 +174,4 @@ Vauxr device (speaker)
 ## License
 
 Vauxr OpenClaw is licensed under the [MIT License](LICENSE).
+

package/dist/index.js

@@ -0,0 +1,60 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { vauxrPlugin } from "./src/channel.js";
+import { VauxrAPIClient } from "./src/api-client.js";
+import { registerTools } from "./src/tools.js";
+import { VauxrBridge } from "./src/bridge.js";
+import { DEFAULT_VOICE_SYSTEM_PROMPT } from "./src/defaults.js";
+function resolveConfig(api) {
+    if (api.pluginConfig && typeof api.pluginConfig === "object" && "url" in api.pluginConfig) {
+        return api.pluginConfig;
+    }
+    const cfg = api.config;
+    const channels = cfg.channels;
+    return (channels?.vauxr ?? {});
+}
+const entry = defineChannelPluginEntry({
+    id: "vauxr",
+    name: "Vauxr",
+    description: "Vauxr voice device channel plugin for OpenClaw",
+    plugin: vauxrPlugin,
+    registerFull(api) {
+        const config = resolveConfig(api);
+        // REST tools — use explicit httpUrl if set, otherwise derive from ws url
+        // (vauxr WS is on :8765, HTTP API is on :8080)
+        const httpBase = config.httpUrl ?? (config.url ? config.url.replace(/:8765(\/?$)/, ":8080") : "");
+        if (!httpBase) {
+            // config.url not available yet (early registration) — skip bridge/tools
+            return;
+        }
+        const client = new VauxrAPIClient(httpBase, config.token ?? "");
+        registerTools(api, client);
+        // Construct the WS bridge but DO NOT start it here. `registerFull` is
+        // invoked from introspection paths too (e.g. `openclaw doctor`), and
+        // starting the bridge here would open a live WebSocket to vauxr during
+        // diagnostics. The bridge is started later by `gateway.startAccount`
+        // (see channel.ts), which only fires when the gateway is actually
+        // bringing the channel up for runtime use. The globalThis stash bridges
+        // the two scopes because `startAccount` doesn't have access to `api`.
+        //
+        // The single-bridge guard remains here so multiple `registerFull`
+        // invocations in the same process don't reconstruct the bridge — they'd
+        // contend for the single active channel slot in vauxr otherwise.
+        const g = globalThis;
+        if (!g.__vauxrBridge) {
+            g.__vauxrBridge = new VauxrBridge(api, config);
+        }
+        // Voice system prompt injection for vauxr sessions. Match both the bare
+        // form (`vauxr:<deviceId>`) used by the old subagent.run path and the
+        // fully-prefixed form (`agent:<agentId>:vauxr:<deviceId>`) used by the
+        // current channel.turn.run path. Either form means it's a vauxr turn.
+        api.on("before_prompt_build", (_event, ctx) => {
+            if (ctx.sessionKey && /(?:^|:)vauxr:/.test(ctx.sessionKey)) {
+                return {
+                    appendSystemContext: config.voiceSystemPrompt ?? DEFAULT_VOICE_SYSTEM_PROMPT,
+                };
+            }
+            return undefined;
+        });
+    },
+});
+export default entry;

package/{setup-entry.ts → dist/setup-entry.js}

@@ -1,4 +1,3 @@
 import { defineSetupPluginEntry } from "openclaw/plugin-sdk/core";
 import { vauxrPlugin } from "./src/channel.js";
-
 export default defineSetupPluginEntry(vauxrPlugin);

package/dist/src/api-client.js

@@ -0,0 +1,61 @@
+export class VauxrAPIClient {
+    baseUrl;
+    token;
+    constructor(baseUrl, token) {
+        this.baseUrl = baseUrl;
+        this.token = token;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            "Content-Type": "application/json",
+        };
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            let message = `HTTP ${res.status}`;
+            try {
+                const errorBody = (await res.json());
+                const detail = errorBody.error ?? errorBody.message;
+                if (typeof detail === "string") {
+                    message = detail;
+                }
+            }
+            catch {
+                // response body wasn't JSON — keep generic message
+            }
+            if (res.status === 401) {
+                throw new Error(`Unauthorized: ${message}`);
+            }
+            if (res.status === 404) {
+                throw new Error(`Device not found: ${message}`);
+            }
+            if (res.status === 409) {
+                throw new Error(`Device busy: ${message}`);
+            }
+            throw new Error(message);
+        }
+        const text = await res.text();
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+    async listDevices() {
+        return this.request("GET", "/api/devices");
+    }
+    async announce(deviceId, text) {
+        await this.request("POST", `/api/devices/${encodeURIComponent(deviceId)}/announce`, {
+            text,
+        });
+    }
+    async command(deviceId, command, params) {
+        await this.request("POST", `/api/devices/${encodeURIComponent(deviceId)}/command`, {
+            command,
+            params,
+        });
+    }
+}

package/dist/src/bridge.js

@@ -0,0 +1,360 @@
+import WebSocket from "ws";
+const INITIAL_RECONNECT_MS = 1000;
+const MAX_RECONNECT_MS = 30000;
+export class VauxrBridge {
+    api;
+    config;
+    ws = null;
+    reconnectMs = INITIAL_RECONNECT_MS;
+    reconnectTimer = null;
+    unsubscribeEvents = null;
+    started = false;
+    // Inflight turns keyed by deviceId. channel.turn.run doesn't surface an SDK
+    // runId to the caller (unlike the old subagent.run path), so dispatch-time
+    // bookkeeping is keyed by deviceId; we then latch onto the SDK runId on the
+    // first event that arrives carrying a sessionKey (typically lifecycle.start)
+    // and use that runId for all subsequent events from the same run. Most
+    // event streams (assistant/tool/item) do NOT carry sessionKey — only the
+    // lifecycle stream does — so runId-based correlation is load-bearing once
+    // we've latched. One inflight turn per device at a time.
+    activeRuns = new Map(); // deviceId → turn
+    runIdToTurn = new Map(); // sdkRunId → turn
+    // Per-device silent-reply sentinel state. "NO_REPLY" often arrives split
+    // across streaming deltas (e.g. "NO" then "_REPLY"), so we buffer until
+    // the accumulated text either matches the sentinel (suppress the whole
+    // run) or diverges (flush and pass through).
+    sentinelBuffer = new Map(); // deviceId → held delta text
+    sentinelMode = new Map();
+    wsUrl;
+    constructor(api, config) {
+        this.api = api;
+        this.config = config;
+        // Derive WS URL from HTTP base URL
+        const base = config.url.replace(/\/$/, "");
+        this.wsUrl = base.replace(/^http/, "ws") + "/channel";
+    }
+    start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.connect();
+        this.subscribeAgentEvents();
+    }
+    stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.unsubscribeEvents) {
+            this.unsubscribeEvents();
+            this.unsubscribeEvents = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        // Reset the backoff so a subsequent stop/start cycle (e.g. channel
+        // aborts then restarts) begins reconnecting at INITIAL_RECONNECT_MS
+        // instead of inheriting whatever escalated delay the previous run
+        // had accumulated.
+        this.reconnectMs = INITIAL_RECONNECT_MS;
+    }
+    connect() {
+        this.api.logger.debug?.(`[vauxr-bridge] Connecting to vauxr: ${this.wsUrl}`);
+        const ws = new WebSocket(this.wsUrl);
+        this.ws = ws;
+        ws.on("open", () => {
+            this.api.logger.debug?.("[vauxr-bridge] Connected to vauxr");
+            this.reconnectMs = INITIAL_RECONNECT_MS;
+            // Authenticate with channel token
+            if (this.config.token) {
+                this.send({ type: "channel.auth", token: this.config.token });
+            }
+        });
+        ws.on("message", (data) => {
+            try {
+                const frame = JSON.parse(String(data));
+                this.handleFrame(frame);
+            }
+            catch (err) {
+                this.api.logger.warn(`[vauxr-bridge] Failed to parse inbound frame: ${String(err)}`);
+            }
+        });
+        ws.on("close", () => {
+            this.api.logger.debug?.("[vauxr-bridge] Disconnected from vauxr");
+            // Identity check: a stop() during the close-event async delay can be
+            // followed by another start() that opens a fresh ws. If we cleared
+            // `this.ws` blindly here we'd wipe the new socket's reference and
+            // also fire a duplicate reconnect. Only act if we're still the
+            // bridge's current ws.
+            if (this.ws !== ws)
+                return;
+            this.ws = null;
+            if (this.started)
+                this.scheduleReconnect();
+        });
+        ws.on("error", (err) => {
+            this.api.logger.warn(`[vauxr-bridge] WS error: ${String(err)}`);
+            // 'close' event will fire after this — reconnect handled there
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.api.logger.debug?.(`[vauxr-bridge] Reconnecting in ${this.reconnectMs}ms`);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, this.reconnectMs);
+        this.reconnectMs = Math.min(this.reconnectMs * 2, MAX_RECONNECT_MS);
+    }
+    handleFrame(frame) {
+        switch (frame.type) {
+            case "channel.transcript":
+                if (frame.deviceId && frame.text) {
+                    void this.dispatchTranscript(frame.deviceId, frame.text);
+                }
+                break;
+            case "channel.device_state":
+                this.api.logger.info(`[vauxr-bridge] Device ${frame.deviceId ?? "unknown"}: ${frame.state ?? "unknown"}`);
+                break;
+            case "channel.ready":
+                this.api.logger.debug?.("[vauxr-bridge] Channel authenticated");
+                break;
+            case "error":
+                this.api.logger.warn(`[vauxr-bridge] Error from vauxr: ${frame.code ?? "UNKNOWN"} — ${frame.message ?? "no details"}`);
+                break;
+            default:
+                this.api.logger.warn(`[vauxr-bridge] Unknown frame type: ${String(frame.type)}`);
+        }
+    }
+    async dispatchTranscript(deviceId, text) {
+        const cfg = this.api.config;
+        // Construct the sessionKey in the same form the old subagent.run path
+        // ended up producing after openclaw's internal normalization
+        // (`agent:<agentId>:vauxr:<deviceId>`). channel.turn.run does NOT apply
+        // that same normalization to routeSessionKey — it stores under whatever
+        // string we pass — so we have to build the full form ourselves to
+        // preserve session continuity with prior turns / restarts.
+        const agentId = resolveTargetAgentId(cfg);
+        const sessionKey = `agent:${agentId}:vauxr:${deviceId}`;
+        // Protocol-level runId sent to vauxr-ws in response frames so it can
+        // correlate delta/end/error chunks back to this transcript.
+        const protocolRunId = crypto.randomUUID();
+        const turnId = `vauxr-${deviceId}-${Date.now()}`;
+        this.api.logger.info(`[vauxr-bridge] Dispatching transcript for ${sessionKey} (runId=${protocolRunId}): "${text}"`);
+        // Register before dispatch so onAgentEvent can correlate any event the
+        // agent runtime emits for this turn back to the originating device.
+        this.activeRuns.set(deviceId, { deviceId, protocolRunId });
+        const storePath = this.api.runtime.channel.session.resolveStorePath(cfg.session?.store);
+        // Minimal inbound context. Voice channels don't carry replies, media,
+        // mentions, forwards, etc. — most MsgContext fields stay undefined.
+        const ctxPayload = {
+            Body: text,
+            BodyForAgent: text,
+            From: deviceId,
+            SenderId: deviceId,
+            SenderName: deviceId,
+            SessionKey: sessionKey,
+            Provider: "vauxr",
+            Surface: "vauxr",
+            Timestamp: Date.now(),
+        };
+        try {
+            // OpenClaw 2026.5.28 renamed `runtime.channel.turn` to
+            // `runtime.channel.inbound` (pure rename — same signature, same
+            // ChannelInboundEventRunnerParams shape as the prior
+            // RunChannelTurnParams). Earlier vauxr-openclaw releases that
+            // referenced `.turn.run` will throw `Cannot read properties of
+            // undefined (reading 'run')` on gateways 2026.5.28+.
+            await this.api.runtime.channel.inbound.run({
+                channel: "vauxr",
+                raw: { deviceId, text },
+                adapter: {
+                    ingest: () => ({
+                        id: turnId,
+                        timestamp: Date.now(),
+                        rawText: text,
+                        raw: { deviceId, text },
+                    }),
+                    classify: () => ({ kind: "message", canStartAgentTurn: true }),
+                    resolveTurn: () => ({
+                        channel: "vauxr",
+                        routeSessionKey: sessionKey,
+                        storePath,
+                        // FinalizedMsgContext has ~80 optional fields; ours is a minimal
+                        // voice-channel subset. The kernel reads what it needs and ignores
+                        // the rest, so an unsafe cast is acceptable here.
+                        ctxPayload: ctxPayload,
+                        recordInboundSession: this.api.runtime.channel.session.recordInboundSession,
+                        runDispatch: async () => {
+                            // Outbound delivery flows through the existing onAgentEvent
+                            // delta tap (subscribeAgentEvents) for lowest TTS latency — see
+                            // spec decision D2. The reply dispatcher's `deliver` is a no-op
+                            // here; the dispatcher exists only to satisfy the channel-turn
+                            // contract and to give the dispatch-from-config pipeline a sink
+                            // to write into.
+                            const { dispatcher } = this.api.runtime.channel.reply.createReplyDispatcherWithTyping({
+                                deliver: async () => undefined,
+                            });
+                            return await this.api.runtime.channel.reply.dispatchReplyFromConfig({
+                                ctx: ctxPayload,
+                                cfg,
+                                dispatcher,
+                            });
+                        },
+                    }),
+                },
+            });
+        }
+        catch (err) {
+            this.api.logger.warn(`[vauxr-bridge] Failed to dispatch transcript for ${sessionKey}: ${String(err)}`);
+            this.send({
+                type: "channel.response.error",
+                deviceId,
+                runId: protocolRunId,
+                message: String(err),
+            });
+        }
+        finally {
+            // channel.turn.run awaits the full turn (including the agent run inside
+            // runDispatch), so by this point all events have fired and the turn is
+            // done. Safe to clean up correlation state here. runIdToTurn entries
+            // for this device are cleaned in the lifecycle.end branch of the event
+            // handler — best-effort sweep here in case lifecycle.end never fired.
+            this.activeRuns.delete(deviceId);
+            this.sentinelBuffer.delete(deviceId);
+            this.sentinelMode.delete(deviceId);
+            for (const [rid, turn] of this.runIdToTurn) {
+                if (turn.deviceId === deviceId)
+                    this.runIdToTurn.delete(rid);
+            }
+        }
+    }
+    subscribeAgentEvents() {
+        this.unsubscribeEvents = this.api.runtime.events.onAgentEvent((event) => {
+            // Two-stage correlation:
+            //   1. If the event carries a sessionKey (lifecycle events do, most
+            //      others don't), parse the deviceId and look up the inflight turn
+            //      we registered in dispatchTranscript. Cache the SDK runId so
+            //      subsequent sessionKey-less events from the same run can be
+            //      matched by runId alone.
+            //   2. Otherwise, look up by event.runId — populated by step (1) for
+            //      this turn's prior lifecycle event.
+            // pi-embedded's first lifecycle.start carries sessionKey and arrives
+            // well before any assistant deltas, so the latch is always primed
+            // before delta events need to route.
+            let active;
+            const sk = event.sessionKey;
+            if (sk) {
+                const m = sk.match(/(?:^|:)vauxr:([^:]+)/);
+                if (m) {
+                    active = this.activeRuns.get(m[1]);
+                    if (active)
+                        this.runIdToTurn.set(event.runId, active);
+                }
+            }
+            if (!active)
+                active = this.runIdToTurn.get(event.runId);
+            if (!active)
+                return;
+            const { deviceId, protocolRunId: runId } = active;
+            if (event.stream === "assistant") {
+                // Only forward the incremental delta. data.text is the running
+                // accumulated reply — forwarding it as a delta would re-send
+                // the entire reply on top of the deltas we've already sent,
+                // duplicating it in TTS. The OpenClaw runtime emits at least
+                // one final assistant event per run with `{ text }` only (no
+                // `delta`); those carry no new content and must be dropped.
+                const delta = event.data["delta"];
+                if (typeof delta !== "string" || delta.length === 0)
+                    return;
+                const mode = this.sentinelMode.get(deviceId);
+                if (mode === "suppressed")
+                    return;
+                if (mode === "passthrough") {
+                    this.send({ type: "channel.response.delta", deviceId, runId, text: delta });
+                    return;
+                }
+                // Buffering: hold deltas while the accumulated text could
+                // still complete the silent-reply sentinel.
+                const SENTINEL = "NO_REPLY";
+                const buffered = (this.sentinelBuffer.get(deviceId) ?? "") + delta;
+                const normalized = buffered.trim().toUpperCase();
+                if (normalized === SENTINEL) {
+                    // Confirmed sentinel — suppress everything for this run.
+                    this.sentinelMode.set(deviceId, "suppressed");
+                    this.sentinelBuffer.delete(deviceId);
+                    return;
+                }
+                if (SENTINEL.startsWith(normalized)) {
+                    // Could still become the sentinel — keep holding.
+                    this.sentinelBuffer.set(deviceId, buffered);
+                    return;
+                }
+                // Diverged from sentinel — flush the held text and pass through
+                // the rest of the run.
+                this.sentinelMode.set(deviceId, "passthrough");
+                this.sentinelBuffer.delete(deviceId);
+                this.send({ type: "channel.response.delta", deviceId, runId, text: buffered });
+            }
+            // Signal end-of-turn to vauxr-ws so TTS finalizes. dispatchTranscript's
+            // finally clears activeRuns once channel.turn.run returns; we don't
+            // clean up here to avoid racing that path.
+            if (event.stream === "lifecycle" && event.data["phase"] === "end") {
+                this.send({
+                    type: "channel.response.end",
+                    deviceId,
+                    runId,
+                });
+            }
+            if (event.stream === "error") {
+                this.api.logger.warn(`[vauxr-bridge] Agent error for device ${deviceId}: ${JSON.stringify(event.data)}`);
+                this.send({
+                    type: "channel.response.error",
+                    deviceId,
+                    runId,
+                    message: String(event.data["message"] ?? "Agent error"),
+                });
+            }
+        });
+    }
+    send(frame) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(frame));
+        }
+    }
+}
+/**
+ * Resolve the agent id that vauxr turns should route to.
+ *
+ * Preference order:
+ *   1. channels.vauxr.targetAgent (explicit operator config)
+ *   2. plugins.entries.vauxr.config.targetAgent (alternate config slot)
+ *   3. agents.list[].default === true
+ *   4. agents.list[0].id (first declared agent)
+ *   5. "default" sentinel (last resort — produces an obviously-wrong key the
+ *      operator can spot in logs)
+ */
+function resolveTargetAgentId(cfg) {
+    const raw = cfg;
+    const fromChannels = raw.channels?.vauxr;
+    if (fromChannels?.targetAgent)
+        return fromChannels.targetAgent;
+    const fromPlugins = raw.plugins?.entries?.vauxr;
+    if (fromPlugins?.config?.targetAgent)
+        return fromPlugins.config.targetAgent;
+    const agents = raw.agents
+        ?.list;
+    if (Array.isArray(agents)) {
+        const defaultAgent = agents.find((a) => a.default && a.id);
+        if (defaultAgent?.id)
+            return defaultAgent.id;
+        if (agents[0]?.id)
+            return agents[0].id;
+    }
+    return "default";
+}