@voicyclaw/voicyclaw 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaoshen Luo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# VoicyClaw OpenClaw Plugin
+
+This package is the standalone OpenClaw plugin for VoicyClaw.
+
+Current scope:
+
+- registers a real `voicyclaw` channel plugin
+- owns an outbound WebSocket gateway connector
+- performs the VoicyClaw `HELLO` / `WELCOME` handshake
+- forwards final `STT_RESULT` turns into the OpenClaw agent runtime
+- maps OpenClaw block/final replies back into VoicyClaw preview/text events
+- tracks connection status through `voicyclaw.status`
+- keeps a guarded `devEchoReplies` mode for transport smoke tests
+
+What is not wired yet:
+
+- audio frame handling beyond the protocol skeleton
+- richer non-text payload delivery beyond text plus attachment URLs
+
+## Local Development
+
+Install dependencies inside this directory. Because this package lives inside
+the main VoicyClaw monorepo but stays intentionally outside the workspace, use
+`--ignore-workspace` for the initial install so pnpm creates the standalone
+lockfile here.
+
+```bash
+pnpm install --ignore-workspace
+```
+
+Run the local checks for the standalone package:
+
+```bash
+pnpm lint
+pnpm test
+pnpm typecheck
+```
+
+The test suite includes a wire-level smoke case that covers the minimal
+VoicyClaw workflow:
+
+- `HELLO`
+- `WELCOME`
+- `STT_RESULT`
+- `BOT_PREVIEW`
+- `TTS_TEXT`
+
+## Link Into OpenClaw
+
+```bash
+openclaw plugins install --link /Users/lyshen/Desktop/project/VoicyClaw/extensions/voicyclaw
+openclaw gateway restart
+```
+
+## Channel Config
+
+Configure the connector under `channels.voicyclaw`.
+
+Minimal local example:
+
+```json
+{
+  "channels": {
+    "voicyclaw": {
+      "url": "http://127.0.0.1:3001",
+      "token": "vc_xxx",
+      "channelId": "demo-room",
+      "botId": "openclaw-local",
+      "displayName": "OpenClaw Local"
+    }
+  }
+}
+```
+
+Important:
+
+- `channels.voicyclaw.token` is the VoicyClaw API key issued by the VoicyClaw
+  server
+- it is not the same thing as `gateway.auth.token` from OpenClaw
+- if the wrong token is configured, the OpenClaw logs will show
+  `AUTH_FAILED Invalid or expired API key.`
+
+Optional development-only transport echo:
+
+```json
+{
+  "channels": {
+    "voicyclaw": {
+      "devEchoReplies": true
+    }
+  }
+}
+```
+
+When `devEchoReplies` is enabled, the plugin sends a simple echoed `TTS_TEXT`
+reply after a final transcript arrives, bypassing the real OpenClaw dispatch
+path. That is only for isolating transport problems during local debugging.

package/index.ts

@@ -0,0 +1,28 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+
+import { createVoicyClawChannel } from "./src/channel.js";
+import { createVoicyClawRuntime, setVoicyClawRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "voicyclaw",
+  name: "VoicyClaw",
+  description: "Outbound VoicyClaw channel connector for OpenClaw",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    const runtime = createVoicyClawRuntime();
+
+    setVoicyClawRuntime(runtime);
+
+    api.registerChannel({
+      plugin: createVoicyClawChannel(runtime, api.runtime.channel),
+    });
+    api.registerGatewayMethod("voicyclaw.status", ({ respond }) => {
+      respond(true, {
+        accounts: runtime.listSnapshots(),
+      });
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "voicyclaw",
+  "channels": ["voicyclaw"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@voicyclaw/voicyclaw",
+  "version": "0.0.2",
+  "private": false,
+  "description": "OpenClaw VoicyClaw channel plugin",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lyshen/VoicyClaw.git",
+    "directory": "extensions/voicyclaw"
+  },
+  "homepage": "https://github.com/Lyshen/VoicyClaw/tree/main/extensions/voicyclaw",
+  "bugs": {
+    "url": "https://github.com/Lyshen/VoicyClaw/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "voicyclaw",
+    "voice"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "README.md",
+    "index.ts",
+    "openclaw.plugin.json",
+    "src/channel.ts",
+    "src/config.ts",
+    "src/dispatch.ts",
+    "src/gateway.ts",
+    "src/protocol.ts",
+    "src/runtime.ts",
+    "src/socket-client.ts",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^25.5.0",
+    "@types/ws": "^8.18.1",
+    "openclaw": "2026.3.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.3.1"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "voicyclaw",
+      "label": "VoicyClaw",
+      "selectionLabel": "VoicyClaw (Outbound Connector)",
+      "detailLabel": "VoicyClaw",
+      "docsPath": "/channels/voicyclaw",
+      "docsLabel": "voicyclaw",
+      "blurb": "Connect OpenClaw outward to a VoicyClaw service over WebSocket.",
+      "aliases": [
+        "voiceclaw"
+      ],
+      "order": 60
+    }
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/channel.ts

@@ -0,0 +1,125 @@
+import type { ChannelPlugin, PluginRuntime } from "openclaw/plugin-sdk";
+
+import {
+  DEFAULT_VOICYCLAW_ACCOUNT_ID,
+  listVoicyClawAccountIds,
+  type ResolvedVoicyClawAccount,
+  resolveVoicyClawAccount,
+  voicyClawChannelConfigSchema,
+} from "./config.js";
+import { createVoicyClawGatewayAdapter } from "./gateway.js";
+import type { VoicyClawRuntime } from "./runtime.js";
+
+export function createVoicyClawChannel(
+  runtimeState: VoicyClawRuntime,
+  channelRuntime: PluginRuntime["channel"],
+): ChannelPlugin<ResolvedVoicyClawAccount> {
+  return {
+    id: "voicyclaw",
+    meta: {
+      id: "voicyclaw",
+      label: "VoicyClaw",
+      selectionLabel: "VoicyClaw (Outbound Connector)",
+      docsPath: "/channels/voicyclaw",
+      blurb:
+        "Outbound VoicyClaw connector that lets OpenClaw attach to a hosted voice workspace.",
+      aliases: ["voiceclaw"],
+    },
+    capabilities: {
+      chatTypes: ["direct"],
+    },
+    reload: {
+      configPrefixes: ["channels.voicyclaw"],
+    },
+    configSchema: voicyClawChannelConfigSchema,
+    config: {
+      listAccountIds: (cfg) => listVoicyClawAccountIds(cfg),
+      resolveAccount: (cfg, accountId) =>
+        resolveVoicyClawAccount(cfg, accountId),
+      defaultAccountId: () => DEFAULT_VOICYCLAW_ACCOUNT_ID,
+      isEnabled: (account) => account.enabled,
+      isConfigured: (account) => account.configured,
+      describeAccount: (account) => ({
+        accountId: account.accountId,
+        name: account.displayName,
+        enabled: account.enabled,
+        configured: account.configured,
+        baseUrl: account.url,
+        audience: account.channelId,
+        tokenSource: account.token ? "config" : undefined,
+      }),
+    },
+    status: {
+      buildAccountSnapshot: ({ account, runtime }) => {
+        const tracked = runtimeState.getSnapshot(account.accountId);
+
+        return {
+          accountId: account.accountId,
+          name: account.displayName,
+          enabled: account.enabled,
+          configured: account.configured,
+          running: tracked?.running ?? runtime?.running ?? false,
+          connected: tracked?.connected ?? runtime?.connected ?? false,
+          reconnectAttempts:
+            tracked?.reconnectAttempts ?? runtime?.reconnectAttempts ?? 0,
+          lastConnectedAt:
+            tracked?.lastConnectedAt ?? runtime?.lastConnectedAt ?? null,
+          lastDisconnect:
+            tracked?.lastDisconnect ?? runtime?.lastDisconnect ?? null,
+          lastError: tracked?.lastError ?? runtime?.lastError ?? null,
+          lastStartAt: tracked?.lastStartAt ?? runtime?.lastStartAt ?? null,
+          lastStopAt: tracked?.lastStopAt ?? runtime?.lastStopAt ?? null,
+          lastMessageAt:
+            tracked?.lastMessageAt ?? runtime?.lastMessageAt ?? null,
+          lastInboundAt:
+            tracked?.lastInboundAt ?? runtime?.lastInboundAt ?? null,
+          lastOutboundAt:
+            tracked?.lastOutboundAt ?? runtime?.lastOutboundAt ?? null,
+          baseUrl: account.url,
+          audience: account.channelId,
+          tokenSource: account.token ? "config" : undefined,
+        };
+      },
+      resolveAccountState: ({ configured, enabled }) => {
+        if (!configured) {
+          return "not configured";
+        }
+
+        return enabled ? "enabled" : "disabled";
+      },
+      collectStatusIssues: (accounts) => {
+        return accounts.flatMap((account) => {
+          const issues = [];
+
+          if (!account.configured) {
+            issues.push({
+              channel: "voicyclaw",
+              accountId: account.accountId,
+              kind: "config" as const,
+              message: "VoicyClaw token is missing.",
+              fix: "Set channels.voicyclaw.token or channels.voicyclaw.accounts.<id>.token.",
+            });
+          }
+
+          if (
+            account.enabled &&
+            account.configured &&
+            !account.connected &&
+            account.lastError
+          ) {
+            issues.push({
+              channel: "voicyclaw",
+              accountId: account.accountId,
+              kind: "runtime" as const,
+              message: `VoicyClaw connector is disconnected: ${account.lastError}`,
+              fix: "Check the VoicyClaw base URL, token, and room id, then restart the gateway.",
+            });
+          }
+
+          return issues;
+        });
+      },
+    },
+    gateway: createVoicyClawGatewayAdapter(runtimeState, channelRuntime),
+  };
+}

package/src/config.ts

@@ -0,0 +1,297 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export const DEFAULT_VOICYCLAW_ACCOUNT_ID = "default";
+export const DEFAULT_VOICYCLAW_BASE_URL = "http://127.0.0.1:3001";
+export const DEFAULT_VOICYCLAW_CHANNEL_ID = "default";
+export const DEFAULT_VOICYCLAW_BOT_ID = "openclaw-voicyclaw";
+export const DEFAULT_VOICYCLAW_DISPLAY_NAME = "VoicyClaw Connector";
+export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
+export const DEFAULT_RECONNECT_BACKOFF_MS = 5_000;
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000;
+
+export type VoicyClawAccountConfig = {
+  enabled?: boolean;
+  url?: string;
+  token?: string;
+  workspaceId?: string;
+  channelId?: string;
+  botId?: string;
+  displayName?: string;
+  connectTimeoutMs?: number;
+  reconnectBackoffMs?: number;
+  heartbeatIntervalMs?: number;
+  devEchoReplies?: boolean;
+};
+
+export type ResolvedVoicyClawAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  url: string;
+  token?: string;
+  workspaceId?: string;
+  channelId: string;
+  botId: string;
+  displayName: string;
+  connectTimeoutMs: number;
+  reconnectBackoffMs: number;
+  heartbeatIntervalMs: number;
+  devEchoReplies: boolean;
+  config: VoicyClawAccountConfig;
+};
+
+const voicyClawAccountProperties = {
+  enabled: { type: "boolean" },
+  url: { type: "string" },
+  token: { type: "string" },
+  workspaceId: { type: "string" },
+  channelId: { type: "string" },
+  botId: { type: "string" },
+  displayName: { type: "string" },
+  connectTimeoutMs: { type: "integer", minimum: 1000 },
+  reconnectBackoffMs: { type: "integer", minimum: 500 },
+  heartbeatIntervalMs: { type: "integer", minimum: 1000 },
+  devEchoReplies: { type: "boolean" },
+} as const;
+
+const voicyClawAccountSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: voicyClawAccountProperties,
+} as const;
+
+export const voicyClawChannelConfigSchema = {
+  schema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      ...voicyClawAccountProperties,
+      accounts: {
+        type: "object",
+        additionalProperties: voicyClawAccountSchema,
+      },
+    },
+  },
+  uiHints: {
+    enabled: {
+      label: "Enabled",
+    },
+    url: {
+      label: "VoicyClaw Base URL",
+      placeholder: "https://voice.example.com",
+    },
+    token: {
+      label: "VoicyClaw Token",
+      sensitive: true,
+    },
+    workspaceId: {
+      label: "Workspace ID",
+      advanced: true,
+    },
+    channelId: {
+      label: "Room / Channel ID",
+    },
+    botId: {
+      label: "Bot ID",
+    },
+    displayName: {
+      label: "Display Name",
+    },
+    connectTimeoutMs: {
+      label: "Connect Timeout (ms)",
+      advanced: true,
+    },
+    reconnectBackoffMs: {
+      label: "Reconnect Backoff (ms)",
+      advanced: true,
+    },
+    heartbeatIntervalMs: {
+      label: "Heartbeat Interval (ms)",
+      advanced: true,
+    },
+    devEchoReplies: {
+      label: "Dev Echo Replies",
+      help: "Only for transport smoke tests before real agent dispatch is wired.",
+      advanced: true,
+    },
+    accounts: {
+      label: "Accounts",
+      advanced: true,
+    },
+  },
+} as const;
+
+export function listVoicyClawAccountIds(cfg: OpenClawConfig) {
+  const section = getVoicyClawSection(cfg);
+  const accounts = asRecord(section.accounts);
+  const accountIds = Object.keys(accounts ?? {}).filter((entry) =>
+    entry.trim(),
+  );
+
+  if (accountIds.length > 0) {
+    return accountIds.sort();
+  }
+
+  return [DEFAULT_VOICYCLAW_ACCOUNT_ID];
+}
+
+export function resolveVoicyClawAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): ResolvedVoicyClawAccount {
+  const normalizedAccountId = normalizeAccountId(accountId);
+  const section = getVoicyClawSection(cfg);
+  const baseConfig = omitAccounts(section);
+  const accountConfig = getVoicyClawAccountOverrides(
+    section,
+    normalizedAccountId,
+  );
+  const mergedConfig = {
+    ...baseConfig,
+    ...accountConfig,
+  };
+
+  const enabled = readBoolean(mergedConfig.enabled, true);
+  const url = readString(mergedConfig.url) ?? DEFAULT_VOICYCLAW_BASE_URL;
+  const token = readString(mergedConfig.token);
+  const workspaceId = readString(mergedConfig.workspaceId);
+  const channelId =
+    readString(mergedConfig.channelId) ?? DEFAULT_VOICYCLAW_CHANNEL_ID;
+  const botId =
+    readString(mergedConfig.botId) ?? buildDefaultBotId(normalizedAccountId);
+  const displayName =
+    readString(mergedConfig.displayName) ??
+    buildDefaultDisplayName(normalizedAccountId);
+  const connectTimeoutMs = readPositiveInteger(
+    mergedConfig.connectTimeoutMs,
+    DEFAULT_CONNECT_TIMEOUT_MS,
+  );
+  const reconnectBackoffMs = readPositiveInteger(
+    mergedConfig.reconnectBackoffMs,
+    DEFAULT_RECONNECT_BACKOFF_MS,
+  );
+  const heartbeatIntervalMs = readPositiveInteger(
+    mergedConfig.heartbeatIntervalMs,
+    DEFAULT_HEARTBEAT_INTERVAL_MS,
+  );
+  const devEchoReplies = readBoolean(mergedConfig.devEchoReplies, false);
+
+  return {
+    accountId: normalizedAccountId,
+    enabled,
+    configured: Boolean(token),
+    url,
+    token,
+    workspaceId,
+    channelId,
+    botId,
+    displayName,
+    connectTimeoutMs,
+    reconnectBackoffMs,
+    heartbeatIntervalMs,
+    devEchoReplies,
+    config: {
+      enabled,
+      url,
+      token,
+      workspaceId,
+      channelId,
+      botId,
+      displayName,
+      connectTimeoutMs,
+      reconnectBackoffMs,
+      heartbeatIntervalMs,
+      devEchoReplies,
+    },
+  };
+}
+
+export function buildVoicyClawSocketUrl(input: string | undefined) {
+  const raw = (input?.trim() || DEFAULT_VOICYCLAW_BASE_URL).trim();
+  const withScheme = /^(wss?|https?):\/\//i.test(raw) ? raw : `http://${raw}`;
+  const url = new URL(withScheme);
+
+  if (url.protocol === "http:") {
+    url.protocol = "ws:";
+  } else if (url.protocol === "https:") {
+    url.protocol = "wss:";
+  }
+
+  if (!url.pathname || url.pathname === "/") {
+    url.pathname = "/bot/connect";
+  } else if (!url.pathname.endsWith("/bot/connect")) {
+    url.pathname = `${url.pathname.replace(/\/$/, "")}/bot/connect`;
+  }
+
+  url.hash = "";
+  return url.toString();
+}
+
+function getVoicyClawSection(cfg: OpenClawConfig) {
+  return asRecord(cfg.channels?.voicyclaw);
+}
+
+function getVoicyClawAccountOverrides(
+  section: Record<string, unknown>,
+  accountId: string,
+) {
+  const accounts = asRecord(section.accounts);
+  if (!accounts) {
+    return {};
+  }
+
+  return asRecord(accounts[accountId]);
+}
+
+function omitAccounts(section: Record<string, unknown>) {
+  const { accounts: _accounts, ...rest } = section;
+  return rest;
+}
+
+function buildDefaultBotId(accountId: string) {
+  if (accountId === DEFAULT_VOICYCLAW_ACCOUNT_ID) {
+    return DEFAULT_VOICYCLAW_BOT_ID;
+  }
+
+  return `${DEFAULT_VOICYCLAW_BOT_ID}-${accountId}`;
+}
+
+function buildDefaultDisplayName(accountId: string) {
+  if (accountId === DEFAULT_VOICYCLAW_ACCOUNT_ID) {
+    return DEFAULT_VOICYCLAW_DISPLAY_NAME;
+  }
+
+  return `${DEFAULT_VOICYCLAW_DISPLAY_NAME} ${accountId}`;
+}
+
+function normalizeAccountId(accountId?: string | null) {
+  const normalized = accountId?.trim();
+  return normalized || DEFAULT_VOICYCLAW_ACCOUNT_ID;
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value as Record<string, unknown>;
+}
+
+function readString(value: unknown) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+
+  const normalized = value.trim();
+  return normalized || undefined;
+}
+
+function readBoolean(value: unknown, fallback: boolean) {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function readPositiveInteger(value: unknown, fallback: number) {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}