@voiceclaw/voiceclaw-plugin 1.0.1

package/README.md

@@ -0,0 +1,45 @@
+# @voiceclaw/voiceclaw-plugin
+
+OpenClaw channel plugin for **VoiceClaw** — control your AI agent with Siri on iOS & macOS.
+
+## What is VoiceClaw?
+
+[VoiceClaw](https://voiceclaw.techartisan.site) is a native iOS & macOS app that lets you talk to your OpenClaw agent via Siri or a lightweight chat interface. Install this plugin to connect your OpenClaw instance to the app.
+
+## Installation
+
+```bash
+openclaw plugins install @voiceclaw/voiceclaw-plugin
+```
+
+## Configuration
+
+Add the VoiceClaw channel to your `openclaw.config.json`:
+
+```json
+{
+  "channels": {
+    "voiceclaw": {
+      "accounts": {
+        "default": {
+          "pairingCode": "<6-digit code>"
+        }
+      }
+    }
+  }
+}
+```
+
+> **Note:** The pairing code is only used for the initial connection. After that, a session token is saved locally and the code is no longer needed.
+
+## Pairing
+
+1. Open the **VoiceClaw** app on your iPhone or Mac
+2. Copy the 6-digit pairing code
+3. Paste it as `pairingCode` in your OpenClaw config
+4. Restart OpenClaw
+5. Tap **"I've Configured It"** in the app to verify the connection
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+interface PluginApi {
+    config: Record<string, any>;
+    logger: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        warn: (msg: string) => void;
+    };
+    registerChannel: (opts: {
+        plugin: any;
+    }) => void;
+}
+export default function register(api: PluginApi): void;
+export {};

package/dist/index.js

@@ -0,0 +1,148 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { RelayWsClient } from './ws-client';
+import { DEFAULT_WORKER_URL } from './types';
+const clients = new Map();
+let handleInbound = null;
+// ── Token persistence ──────────────────────────────────────────
+const DATA_DIR = join(homedir(), '.voiceclaw');
+function tokenPath(accountId) {
+    return join(DATA_DIR, `session-${accountId}.token`);
+}
+function loadSavedToken(accountId) {
+    const p = tokenPath(accountId);
+    if (existsSync(p)) {
+        const token = readFileSync(p, 'utf-8').trim();
+        if (token.length > 0)
+            return token;
+    }
+    return null;
+}
+function saveToken(accountId, token) {
+    if (!existsSync(DATA_DIR)) {
+        mkdirSync(DATA_DIR, { recursive: true });
+    }
+    writeFileSync(tokenPath(accountId), token, 'utf-8');
+}
+// ── Pairing code exchange ──────────────────────────────────────
+async function exchangePairingCode(code, workerUrl, logger) {
+    logger.info(`VoiceClaw: Exchanging pairing code for session token...`);
+    const url = `${workerUrl}/pair?code=${encodeURIComponent(code)}`;
+    const resp = await fetch(url, { method: 'POST' });
+    if (!resp.ok) {
+        const body = await resp.text();
+        throw new Error(`Pairing failed (${resp.status}): ${body}`);
+    }
+    const data = (await resp.json());
+    if (!data.sessionToken) {
+        throw new Error('Pairing response missing sessionToken');
+    }
+    logger.info('VoiceClaw: Pairing successful, session token saved');
+    return data.sessionToken;
+}
+/**
+ * Resolve the session token for an account:
+ * 1. If a saved session token exists on disk, use it.
+ * 2. Otherwise, exchange the pairing code and save the result.
+ */
+async function resolveToken(accountId, account, logger) {
+    // Check for a previously saved session token.
+    const saved = loadSavedToken(accountId);
+    if (saved) {
+        logger.info(`VoiceClaw: Using saved session token for "${accountId}"`);
+        return saved;
+    }
+    // No saved token — exchange the pairing code.
+    if (!account.pairingCode) {
+        throw new Error(`No pairing code configured for "${accountId}"`);
+    }
+    const workerUrl = account.workerUrl ?? DEFAULT_WORKER_URL;
+    const sessionToken = await exchangePairingCode(account.pairingCode, workerUrl, logger);
+    saveToken(accountId, sessionToken);
+    return sessionToken;
+}
+// ── Plugin registration ────────────────────────────────────────
+export default function register(api) {
+    const channelId = 'voiceclaw';
+    const voiceClawChannel = {
+        id: channelId,
+        meta: {
+            id: channelId,
+            label: 'VoiceClaw',
+            selectionLabel: 'VoiceClaw (Siri / iOS / macOS)',
+            docsPath: '/channels/voiceclaw',
+            blurb: 'Voice entry for OpenClaw via Siri & native iOS/macOS app.',
+            aliases: ['vc', 'siri'],
+        },
+        capabilities: { chatTypes: ['direct'] },
+        config: {
+            listAccountIds: (cfg) => Object.keys(cfg.channels?.voiceclaw?.accounts ?? {}),
+            resolveAccount: (cfg, accountId) => {
+                const accounts = cfg.channels?.voiceclaw?.accounts ?? {};
+                return accounts[accountId ?? 'default'] ?? {};
+            },
+        },
+        outbound: {
+            deliveryMode: 'direct',
+            sendText: async ({ text, accountId, }) => {
+                const id = accountId ?? 'default';
+                const client = clients.get(id);
+                if (!client || client.connectionState !== 'connected') {
+                    api.logger.warn(`VoiceClaw: No connection for "${id}", reply dropped`);
+                    return { ok: false };
+                }
+                client.send({
+                    type: 'agent_reply',
+                    id: crypto.randomUUID(),
+                    replyTo: '',
+                    text,
+                    ts: new Date().toISOString(),
+                });
+                return { ok: true };
+            },
+        },
+        gateway: {
+            start: async (ctx) => {
+                handleInbound = ctx.processInbound;
+                const accounts = ctx.config.channels?.voiceclaw?.accounts ?? {};
+                for (const [accountId, account] of Object.entries(accounts)) {
+                    if (account.enabled === false)
+                        continue;
+                    try {
+                        const sessionToken = await resolveToken(accountId, account, api.logger);
+                        const workerUrl = account.workerUrl ?? DEFAULT_WORKER_URL;
+                        const client = new RelayWsClient({
+                            token: sessionToken,
+                            workerUrl,
+                            onUserMessage: (msg) => {
+                                api.logger.info(`VoiceClaw: User message (${msg.id}): ${msg.text.slice(0, 50)}...`);
+                                handleInbound?.(msg.text, accountId);
+                            },
+                            onStateChange: (state) => {
+                                api.logger.info(`VoiceClaw: [${accountId}] ${state}`);
+                            },
+                            logger: api.logger,
+                        });
+                        client.start();
+                        clients.set(accountId, client);
+                        api.logger.info(`VoiceClaw: Started relay for "${accountId}"`);
+                    }
+                    catch (err) {
+                        api.logger.error(`VoiceClaw: Failed to start "${accountId}": ${err}`);
+                    }
+                }
+            },
+            stop: () => {
+                for (const [accountId, client] of clients) {
+                    client.stop();
+                    api.logger.info(`VoiceClaw: Stopped "${accountId}"`);
+                }
+                clients.clear();
+                handleInbound = null;
+            },
+        },
+    };
+    api.registerChannel({ plugin: voiceClawChannel });
+    api.logger.info('VoiceClaw channel plugin registered');
+}

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+/** Role of the WebSocket client. */
+export type ClientRole = 'app' | 'plugin';
+/** Auth success (sent by server on connect). */
+export interface AuthOkMessage {
+    type: 'auth_ok';
+}
+/** Auth failure. */
+export interface AuthErrorMessage {
+    type: 'auth_error';
+    reason: string;
+}
+/** User message from app → plugin. */
+export interface UserMessage {
+    type: 'user_message';
+    id: string;
+    text: string;
+    ts: string;
+}
+/** Agent reply from plugin → app. */
+export interface AgentReplyMessage {
+    type: 'agent_reply';
+    id: string;
+    replyTo: string;
+    text: string;
+    ts: string;
+}
+/** Heartbeat. */
+export interface PingMessage {
+    type: 'ping';
+}
+export interface PongMessage {
+    type: 'pong';
+}
+/** Plugin config from channels.voiceclaw.accounts.<id> */
+export interface VoiceClawAccountConfig {
+    pairingCode: string;
+    workerUrl?: string;
+    enabled?: boolean;
+}
+/** Default relay server URL. */
+export declare const DEFAULT_WORKER_URL = "https://voiceclaw-api.techartisan.site";
+/** Messages the plugin receives from the relay. */
+export type InboundRelayMessage = AuthOkMessage | AuthErrorMessage | UserMessage | PongMessage;
+/** Messages the plugin sends to the relay. */
+export type OutboundRelayMessage = AgentReplyMessage | PingMessage;

package/dist/types.js

@@ -0,0 +1,4 @@
+// ── Shared message protocol types ──────────────────────────────
+// Mirrors workers/src/protocol.ts for the plugin side.
+/** Default relay server URL. */
+export const DEFAULT_WORKER_URL = 'https://voiceclaw-api.techartisan.site';

package/dist/ws-client.d.ts

@@ -0,0 +1,46 @@
+import type { OutboundRelayMessage, UserMessage } from './types';
+export type WsClientState = 'disconnected' | 'connecting' | 'connected';
+export interface WsClientOptions {
+    token: string;
+    workerUrl?: string;
+    onUserMessage: (msg: UserMessage) => void;
+    onStateChange?: (state: WsClientState) => void;
+    logger?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+/**
+ * Persistent WebSocket client that connects to the Cloudflare Workers
+ * relay as the "plugin" role. Auth is implicit (the token is the room
+ * key). Handles heartbeat and automatic reconnection with exponential
+ * backoff.
+ */
+export declare class RelayWsClient {
+    private ws;
+    private opts;
+    private state;
+    private reconnectTimer;
+    private heartbeatTimer;
+    private backoffMs;
+    private stopped;
+    private static readonly MAX_BACKOFF_MS;
+    private static readonly HEARTBEAT_MS;
+    constructor(opts: WsClientOptions);
+    /** Start the WebSocket connection. */
+    start(): void;
+    /** Stop and close the WebSocket; no reconnect. */
+    stop(): void;
+    /** Send a message to the relay. */
+    send(msg: OutboundRelayMessage): void;
+    /** Current connection state. */
+    get connectionState(): WsClientState;
+    private connect;
+    private handleMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private cleanup;
+    private setState;
+    private log;
+}

package/dist/ws-client.js

@@ -0,0 +1,146 @@
+import WebSocket from 'ws';
+import { DEFAULT_WORKER_URL } from './types';
+/**
+ * Persistent WebSocket client that connects to the Cloudflare Workers
+ * relay as the "plugin" role. Auth is implicit (the token is the room
+ * key). Handles heartbeat and automatic reconnection with exponential
+ * backoff.
+ */
+export class RelayWsClient {
+    ws = null;
+    opts;
+    state = 'disconnected';
+    reconnectTimer = null;
+    heartbeatTimer = null;
+    backoffMs = 1000;
+    stopped = false;
+    static MAX_BACKOFF_MS = 30_000;
+    static HEARTBEAT_MS = 30_000;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Start the WebSocket connection. */
+    start() {
+        this.stopped = false;
+        this.connect();
+    }
+    /** Stop and close the WebSocket; no reconnect. */
+    stop() {
+        this.stopped = true;
+        this.cleanup();
+        this.setState('disconnected');
+    }
+    /** Send a message to the relay. */
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    /** Current connection state. */
+    get connectionState() {
+        return this.state;
+    }
+    // ── Private ──────────────────────────────────────────────────
+    connect() {
+        if (this.stopped)
+            return;
+        this.cleanup();
+        this.setState('connecting');
+        const base = (this.opts.workerUrl ?? DEFAULT_WORKER_URL).replace(/\/$/, '');
+        const wsUrl = base
+            .replace(/^https:\/\//, 'wss://')
+            .replace(/^http:\/\//, 'ws://');
+        const url = `${wsUrl}/ws?token=${encodeURIComponent(this.opts.token)}&role=plugin`;
+        this.log('info', `Connecting to relay...`);
+        const ws = new WebSocket(url);
+        ws.on('open', () => {
+            this.log('info', 'WebSocket open');
+        });
+        ws.on('message', (data) => {
+            try {
+                const raw = typeof data === 'string' ? data : data.toString();
+                const msg = JSON.parse(raw);
+                this.handleMessage(msg);
+            }
+            catch {
+                this.log('error', `Failed to parse message: ${data}`);
+            }
+        });
+        ws.on('close', () => {
+            this.log('info', 'WebSocket closed');
+            this.setState('disconnected');
+            this.scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            this.log('error', `WebSocket error: ${err.message}`);
+        });
+        this.ws = ws;
+    }
+    handleMessage(msg) {
+        switch (msg.type) {
+            case 'auth_ok':
+                this.log('info', 'Connected and authenticated');
+                this.setState('connected');
+                this.backoffMs = 1000;
+                this.startHeartbeat();
+                break;
+            case 'auth_error':
+                this.log('error', `Auth failed: ${msg.reason}`);
+                this.setState('disconnected');
+                this.stopped = true;
+                break;
+            case 'user_message':
+                this.opts.onUserMessage(msg);
+                break;
+            case 'pong':
+                break;
+        }
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeatTimer = setInterval(() => {
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.ws.send(JSON.stringify({ type: 'ping' }));
+            }
+        }, RelayWsClient.HEARTBEAT_MS);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.log('info', `Reconnecting in ${this.backoffMs}ms...`);
+        this.reconnectTimer = setTimeout(() => {
+            this.connect();
+        }, this.backoffMs);
+        this.backoffMs = Math.min(this.backoffMs * 2, RelayWsClient.MAX_BACKOFF_MS);
+    }
+    cleanup() {
+        this.stopHeartbeat();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            if (this.ws.readyState === WebSocket.OPEN ||
+                this.ws.readyState === WebSocket.CONNECTING) {
+                this.ws.close();
+            }
+            this.ws = null;
+        }
+    }
+    setState(s) {
+        if (this.state === s)
+            return;
+        this.state = s;
+        this.opts.onStateChange?.(s);
+    }
+    log(level, msg) {
+        this.opts.logger?.[level](`[VoiceClaw WS] ${msg}`);
+    }
+}

package/openclaw.plugin.json

@@ -0,0 +1,23 @@
+{
+  "id": "voiceclaw-plugin",
+  "name": "VoiceClaw",
+  "version": "1.0.0",
+  "description": "VoiceClaw channel plugin — Siri & iOS/macOS voice entry for OpenClaw",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "pairingCode": {
+        "type": "string",
+        "description": "6-digit pairing code from the VoiceClaw app (only needed for initial setup)"
+      }
+    },
+    "required": []
+  },
+  "uiHints": {
+    "pairingCode": {
+      "label": "Pairing Code",
+      "placeholder": "The 6-digit code shown in the VoiceClaw app"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@voiceclaw/voiceclaw-plugin",
+  "version": "1.0.1",
+  "description": "OpenClaw channel plugin for VoiceClaw — relay messages between your AI agent and the VoiceClaw iOS/macOS app via Siri",
+  "main": "dist/index.js",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anthropics/voiceclaw"
+  },
+  "homepage": "https://voiceclaw.techartisan.site",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "openclaw-channel",
+    "siri",
+    "voiceclaw",
+    "ios",
+    "macos",
+    "voice"
+  ],
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "dist/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}