@vauxr/openclaw 2026.4.12-0 → 2026.5.24-2

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,55 @@
+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);
+        // WS bridge to vauxr — guard against double-registration.
+        // OpenClaw invokes registerFull from multiple subsystems in the same
+        // process; without this flag, both bridges would contend for the
+        // single active channel slot in vauxr and flap continuously.
+        const g = globalThis;
+        if (!g.__vauxrBridgeStarted) {
+            g.__vauxrBridgeStarted = true;
+            const bridge = new VauxrBridge(api, config);
+            bridge.start();
+        }
+        // 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,334 @@
+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;
+    // 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() {
+        this.connect();
+        this.subscribeAgentEvents();
+    }
+    stop() {
+        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;
+        }
+    }
+    connect() {
+        this.api.logger.info(`[vauxr-bridge] Connecting to vauxr: ${this.wsUrl}`);
+        const ws = new WebSocket(this.wsUrl);
+        this.ws = ws;
+        ws.on("open", () => {
+            this.api.logger.info("[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.info("[vauxr-bridge] Disconnected from vauxr");
+            this.ws = null;
+            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.info(`[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.info("[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 {
+            await this.api.runtime.channel.turn.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";
+}

package/dist/src/channel.js

@@ -0,0 +1,153 @@
+import { createChatChannelPlugin, createChannelPluginBase } from "openclaw/plugin-sdk/core";
+import { DEFAULT_VOICE_SYSTEM_PROMPT } from "./defaults.js";
+import { createTopLevelChannelConfigBase } from "openclaw/plugin-sdk/channel-config-helpers";
+// Type assertion needed: createChannelPluginBase marks capabilities as Partial
+// in its return type, but createChatChannelPlugin requires it non-optional.
+// We always provide capabilities, so the assertion is safe.
+export const vauxrPlugin = createChatChannelPlugin({
+    base: createChannelPluginBase({
+        id: "vauxr",
+        meta: { label: "Vauxr" },
+        capabilities: {
+            chatTypes: ["direct"],
+        },
+        config: createTopLevelChannelConfigBase({
+            sectionKey: "vauxr",
+            resolveAccount: (cfg) => {
+                const section = resolveSection(cfg);
+                const url = section?.url;
+                return {
+                    accountId: url ?? "default",
+                    // running/connected drive UI status indicators
+                    ...(url ? { running: true, connected: true } : {}),
+                };
+            },
+            // Single-account channel — listAccountIds returns either the single
+            // resolved id or an empty array if the channel isn't configured.
+            listAccountIds: (cfg) => {
+                const section = resolveSection(cfg);
+                return section?.url ? [section.url] : [];
+            },
+            defaultAccountId: (cfg) => resolveSection(cfg)?.url ?? "default",
+        }),
+        setup: {
+            resolveAccountId({ cfg }) {
+                const section = resolveSection(cfg);
+                return section?.url ?? "default";
+            },
+            applyAccountConfig({ cfg, input }) {
+                const updated = structuredClone(cfg);
+                const channels = (updated.channels ?? {});
+                const merged = {
+                    // Seed default voice system prompt so it's populated on first install.
+                    // Existing value (if any) takes precedence via spread order.
+                    voiceSystemPrompt: DEFAULT_VOICE_SYSTEM_PROMPT,
+                    ...(channels.vauxr ?? {}),
+                    ...input,
+                };
+                channels.vauxr = merged;
+                updated.channels = channels;
+                applyToolsBySenderPolicy(updated, merged);
+                return updated;
+            },
+        },
+    }),
+    // No security/pairing — vauxr devices are trusted local hardware
+    outbound: {
+        // Outbound responses are delivered via the WS bridge, not the outbound adapter
+        // This stub satisfies the ChannelPlugin interface
+        base: {
+            deliveryMode: "direct",
+        },
+        attachedResults: {
+            channel: "vauxr",
+            sendText: async () => ({ messageId: "bridge" }),
+        },
+    },
+});
+// gateway.startAccount is required for OpenClaw to mark this channel as
+// "running" and "configured" in the UI. The actual bridge lifecycle is
+// managed by registerFull in index.ts (which has access to the full plugin
+// API). This stub holds the channel in running state until the gateway stops.
+// isConfigured: tells OpenClaw the channel is configured when url is set.
+vauxrPlugin.config.isConfigured = (_account, cfg) => {
+    return Boolean(resolveSection(cfg)?.url);
+};
+vauxrPlugin.gateway = {
+    startAccount: async (ctx) => {
+        await new Promise((resolve) => {
+            ctx.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+        });
+    },
+};
+function resolveSection(cfg) {
+    const raw = cfg;
+    const channelsCfg = raw.channels?.vauxr;
+    const pluginsCfg = raw.plugins?.entries?.vauxr;
+    return channelsCfg ?? pluginsCfg?.config;
+}
+// Key used by OpenClaw's per-sender tool policy resolver to match
+// vauxr-originated runs. Format is `channel:<channelId>:<senderId>`;
+// wildcard senderId applies to every vauxr device.
+const VAUXR_TOOLS_BY_SENDER_KEY = "channel:vauxr:*";
+/**
+ * Mirror the vauxr channel's alsoAllow/targetAgent into the target agent's
+ * tools.toolsBySender map. Without this expansion, vauxr-originated runs only
+ * receive the messaging-profile defaults — platform tools like `gateway` and
+ * `nodes` are stripped because the runtime treats third-party channels more
+ * strictly than the internal `webchat` channel.
+ *
+ * Throws when alsoAllow is set without a resolvable targetAgent so the
+ * mismatch surfaces during install/configure instead of silently no-op'ing.
+ */
+function applyToolsBySenderPolicy(cfgMut, section) {
+    const alsoAllow = Array.isArray(section.alsoAllow)
+        ? section.alsoAllow.filter((v) => typeof v === "string")
+        : [];
+    const targetAgent = typeof section.targetAgent === "string" && section.targetAgent.length > 0
+        ? section.targetAgent
+        : undefined;
+    const agentsRoot = (cfgMut.agents ?? {});
+    const agentList = Array.isArray(agentsRoot.list)
+        ? agentsRoot.list
+        : [];
+    if (alsoAllow.length > 0) {
+        if (!targetAgent) {
+            throw new Error("channels.vauxr.alsoAllow is set but channels.vauxr.targetAgent is missing. " +
+                "Set targetAgent to the agent id that handles vauxr sessions (e.g. \"nova-cloud\").");
+        }
+        if (!agentList.some((a) => a.id === targetAgent)) {
+            const known = agentList.map((a) => a.id).filter(Boolean).join(", ") || "(none)";
+            throw new Error(`channels.vauxr.targetAgent="${targetAgent}" does not match any agent in agents.list. ` +
+                `Known agents: ${known}.`);
+        }
+    }
+    // Walk every agent: write the vauxr policy on the target, scrub it from
+    // the others. Idempotent: re-running with the same config is a no-op,
+    // re-running after clearing alsoAllow removes the policy everywhere.
+    for (const agent of agentList) {
+        const tools = (agent.tools ?? {});
+        const toolsBySender = (tools.toolsBySender ?? {});
+        const isTarget = agent.id === targetAgent && alsoAllow.length > 0;
+        if (isTarget) {
+            toolsBySender[VAUXR_TOOLS_BY_SENDER_KEY] = { alsoAllow };
+            tools.toolsBySender = toolsBySender;
+            agent.tools = tools;
+        }
+        else if (VAUXR_TOOLS_BY_SENDER_KEY in toolsBySender) {
+            delete toolsBySender[VAUXR_TOOLS_BY_SENDER_KEY];
+            if (Object.keys(toolsBySender).length === 0) {
+                delete tools.toolsBySender;
+            }
+            else {
+                tools.toolsBySender = toolsBySender;
+            }
+            if (Object.keys(tools).length === 0) {
+                delete agent.tools;
+            }
+            else {
+                agent.tools = tools;
+            }
+        }
+    }
+}

package/dist/src/defaults.js

@@ -0,0 +1 @@
+export const DEFAULT_VOICE_SYSTEM_PROMPT = "You are responding to a voice device. Use plain speech only — no emojis, no markdown, no code blocks. Keep replies concise.";