@alfe.ai/openclaw-voice 0.0.1

package/README.md

@@ -0,0 +1,49 @@
+# packages/openclaw-voice (`@alfe.ai/openclaw-voice`)
+
+OpenClaw voice plugin for Alfe — Discord audio, Twilio phone calls, and meeting bots.
+
+## What It Does
+
+OpenClaw plugin that integrates voice capabilities into the agent runtime. All heavy voice logic lives in `voice-service` — this package is the OpenClaw integration layer.
+
+On activation, the plugin:
+
+- **Registers voice tools** — `voice_hangup`, `voice_transfer` (Twilio), `voice_dtmf` (Twilio)
+- **Registers HTTP routes** — `/twilio/inbound` and `/twilio/status` webhook handlers
+- **Registers gateway RPC** — `voice.speak` for TTS and direct audio output
+- **Hooks into OpenClaw events** — auto-joins/leaves Discord voice on session start/end, auto-injects session IDs into tool calls
+- **Connects to Alfe daemon IPC** — registers voice capabilities; gracefully degrades if unavailable
+
+Follows the standard OpenClaw plugin pattern: exports `id`, `name`, `activate`, `deactivate`.
+
+## Key Files
+
+```
+src/
+├── plugin.ts           # Plugin entry point (activate/deactivate lifecycle, tools, routes, hooks)
+└── index.ts            # Public re-exports
+```
+
+## Session Management
+
+The plugin maintains bidirectional maps between OpenClaw session keys and voice session IDs. On `before_tool_call`, it auto-injects `sessionId` into voice tool parameters so the agent doesn't need to track sessions explicitly.
+
+Discord sessions are detected via the pattern `voice-discord:{guildId}:{channelId}`.
+
+## Development
+
+```bash
+pnpm install
+pnpm --filter @alfe.ai/openclaw-voice build
+```
+
+## Testing
+
+```bash
+pnpm --filter @alfe.ai/openclaw-voice test
+```
+
+## Dependencies
+
+- **voice-service** — core voice logic (TTS, audio pipeline, Discord/Twilio adapters)
+- **@alfe.ai/openclaw** — OpenClaw runtime plugin API

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { TSchema } from "@sinclair/typebox";
+
+//#region src/plugin.d.ts
+
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+interface VoicePluginConfig {
+  voiceServiceUrl?: string;
+  voiceServicePort?: string | number;
+  voiceServiceApiKey?: string;
+  daemonSocket?: string;
+  [key: string]: unknown;
+}
+interface OpenClawConfig {
+  plugins?: {
+    entries?: Record<string, {
+      config?: VoicePluginConfig;
+      [key: string]: unknown;
+    }>;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface OpenClawPluginApi {
+  logger: Logger;
+  config?: OpenClawConfig;
+  registerTool(tool: ToolDef): void;
+  registerGatewayMethod(name: string, handler: (...args: unknown[]) => Promise<unknown>): void;
+  on(event: string, handler: (...args: unknown[]) => void | Promise<void>, options?: {
+    priority?: number;
+  }): void;
+}
+interface ToolDef {
+  name: string;
+  description: string;
+  label: string;
+  parameters: TSchema;
+  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<{
+    content: {
+      type: 'text';
+      text: string;
+    }[];
+    details: unknown;
+  }>;
+}
+declare const plugin: {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  activate(api: OpenClawPluginApi): Promise<void>;
+  deactivate(api: OpenClawPluginApi): void;
+};
+//#endregion
+export { plugin as default };

package/dist/index.js

@@ -0,0 +1,266 @@
+import { Type } from "@sinclair/typebox";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/plugin.ts
+/**
+* @alfe/voice-plugin — OpenClaw native plugin
+*
+* Thin client that registers voice tools with OpenClaw and forwards
+* all operations to the voice service over HTTP. The plugin holds no
+* credentials and imports nothing from the voice service.
+*/
+const DEFAULT_SOCKET_PATH = join(homedir(), ".alfe", "gateway.sock");
+const VOICE_CAPABILITIES = [
+	"voice.call",
+	"voice.answer",
+	"voice.dtmf",
+	"voice.hangup"
+];
+let voiceServiceUrl = "";
+let voiceServiceApiKey = "";
+async function voiceApi(method, path, body) {
+	const url = `${voiceServiceUrl}${path}`;
+	const headers = { "Content-Type": "application/json" };
+	if (voiceServiceApiKey) headers["x-api-key"] = voiceServiceApiKey;
+	const res = await fetch(url, {
+		method,
+		headers,
+		body: body ? JSON.stringify(body) : void 0
+	});
+	const json = await res.json();
+	if (!res.ok) {
+		const errorMsg = typeof json.error === "string" ? json.error : `Voice service returned ${String(res.status)}`;
+		throw new Error(errorMsg);
+	}
+	return json;
+}
+let daemonIpcClient = null;
+async function connectToDaemon(socketPath, log) {
+	try {
+		const IPCClientCtor = (await import("@alfe.ai/openclaw")).IPCClient;
+		const client = new IPCClientCtor(socketPath, log);
+		client.on("connected", async () => {
+			log.info("Connected to Alfe daemon — registering voice capabilities...");
+			const response = await client.request("capability.register", {
+				plugin: "@alfe.ai/openclaw-voice",
+				capabilities: [...VOICE_CAPABILITIES]
+			});
+			if (response.ok) log.info("Voice capabilities registered with daemon");
+			else log.warn(`Failed to register voice capabilities: ${response.error?.message ?? "unknown"}`);
+		});
+		client.on("disconnected", (reason) => {
+			log.warn(`Disconnected from Alfe daemon: ${String(reason)}`);
+		});
+		client.on("error", (err) => {
+			log.debug(`Daemon IPC error: ${err.message}`);
+		});
+		client.start();
+		return client;
+	} catch {
+		log.info("Alfe daemon not available — voice plugin running standalone");
+		return null;
+	}
+}
+function ok(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data)
+		}],
+		details: data
+	};
+}
+function errResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error: message })
+		}],
+		details: { error: message }
+	};
+}
+function defineTool(def) {
+	return {
+		name: def.name,
+		description: def.description,
+		label: def.name,
+		parameters: def.parameters,
+		execute: async (_toolCallId, params) => {
+			try {
+				return ok(await def.handler(params));
+			} catch (e) {
+				return errResult(e.message);
+			}
+		}
+	};
+}
+/** Maps OpenClaw session keys to voice session IDs */
+const sessionKeyToVoiceId = /* @__PURE__ */ new Map();
+/** Maps voice session IDs back to OpenClaw session keys */
+const voiceIdToSessionKey = /* @__PURE__ */ new Map();
+function linkSession(sessionKey, voiceSessionId) {
+	sessionKeyToVoiceId.set(sessionKey, voiceSessionId);
+	voiceIdToSessionKey.set(voiceSessionId, sessionKey);
+}
+function unlinkSession(sessionKey) {
+	const voiceId = sessionKeyToVoiceId.get(sessionKey);
+	if (voiceId) {
+		voiceIdToSessionKey.delete(voiceId);
+		sessionKeyToVoiceId.delete(sessionKey);
+	}
+}
+async function findVoiceSessionForAgent(sessionKey) {
+	const direct = sessionKeyToVoiceId.get(sessionKey);
+	if (direct) return direct;
+	const discordMatch = /voice-discord[:-](\S+)/.exec(sessionKey);
+	if (discordMatch) try {
+		const sessions = (await voiceApi("GET", "/api/discord/sessions")).sessions ?? [];
+		for (const s of sessions) if (s.sessionId.includes(discordMatch[1]) || sessionKey.includes(s.sessionId)) return s.sessionId;
+	} catch {}
+}
+async function findVoiceSessionForCurrentContext() {
+	try {
+		const sessions = (await voiceApi("GET", "/api/discord/sessions")).sessions ?? [];
+		if (sessions.length === 1) return sessions[0].sessionId;
+	} catch {}
+}
+const voiceTools = [
+	defineTool({
+		name: "voice_hangup",
+		description: "Hang up the current voice call or leave the voice channel. Use when the conversation is done or the user asks you to leave.",
+		parameters: Type.Object({ sessionId: Type.Optional(Type.String({ description: "Voice session ID. If omitted, uses the current session." })) }),
+		handler: async (params) => {
+			const sid = params.sessionId ?? await findVoiceSessionForCurrentContext();
+			if (!sid) throw new Error("No active voice session found");
+			try {
+				if ((await voiceApi("GET", `/api/status/${encodeURIComponent(sid)}`)).sessionType === "discord") return await voiceApi("POST", `/api/discord/leave/${encodeURIComponent(sid)}`);
+			} catch {}
+			return await voiceApi("POST", `/api/leave/${encodeURIComponent(sid)}`);
+		}
+	}),
+	defineTool({
+		name: "voice_transfer",
+		description: "Transfer the current phone call to another number. Only works for Twilio calls.",
+		parameters: Type.Object({
+			targetNumber: Type.String({ description: "Phone number to transfer to (E.164 format)" }),
+			sessionId: Type.Optional(Type.String({ description: "Voice session ID. If omitted, uses the current session." }))
+		}),
+		handler: async (params) => {
+			const targetNumber = params.targetNumber;
+			const sid = params.sessionId ?? await findVoiceSessionForCurrentContext();
+			if (!sid) throw new Error("No active voice session found");
+			return await voiceApi("POST", `/api/transfer/${encodeURIComponent(sid)}`, { targetNumber });
+		}
+	}),
+	defineTool({
+		name: "voice_dtmf",
+		description: "Send DTMF tones (dial pad digits) on the current phone call. Only works for Twilio calls.",
+		parameters: Type.Object({
+			digits: Type.String({ description: "DTMF digits to send (0-9, *, #, w for pause)" }),
+			sessionId: Type.Optional(Type.String({ description: "Voice session ID. If omitted, uses the current session." }))
+		}),
+		handler: async (params) => {
+			const digits = params.digits;
+			const sid = params.sessionId ?? await findVoiceSessionForCurrentContext();
+			if (!sid) throw new Error("No active voice session found");
+			return await voiceApi("POST", `/api/dtmf/${encodeURIComponent(sid)}`, { digits });
+		}
+	})
+];
+const voiceToolNames = new Set(voiceTools.map((t) => t.name));
+const plugin = {
+	id: "@alfe.ai/openclaw-voice",
+	name: "Alfe Voice Plugin",
+	description: "Real-time voice integration — Twilio phone calls, Discord voice channels, and meeting bots",
+	version: "0.1.0",
+	async activate(api) {
+		if (globalThis.__voiceGatewayActivated) {
+			api.logger.debug("Alfe Voice plugin already activated, skipping re-init");
+			return;
+		}
+		globalThis.__voiceGatewayActivated = true;
+		const log = api.logger;
+		log.info("Alfe Voice plugin activating...");
+		const fullConfig = api.config ?? {};
+		const pluginConfig = fullConfig.plugins?.entries?.["@alfe.ai/openclaw-voice"]?.config ?? fullConfig.plugins?.entries?.["voice-gateway"]?.config ?? {};
+		voiceServiceUrl = pluginConfig.voiceServiceUrl ?? process.env.VOICE_SERVICE_URL ?? `http://localhost:${String(pluginConfig.voiceServicePort ?? process.env.VOICE_SERVICE_PORT ?? "3100")}`;
+		voiceServiceApiKey = pluginConfig.voiceServiceApiKey ?? process.env.VOICE_SERVICE_API_KEY ?? "";
+		log.info(`Voice service: ${voiceServiceUrl}`);
+		daemonIpcClient = await connectToDaemon(pluginConfig.daemonSocket ?? process.env.ALFE_GATEWAY_SOCKET ?? DEFAULT_SOCKET_PATH, log);
+		for (const tool of voiceTools) api.registerTool(tool);
+		log.info(`Registered ${String(voiceTools.length)} voice tools: ${voiceTools.map((t) => t.name).join(", ")}`);
+		api.registerGatewayMethod("voice.speak", async (...args) => {
+			const { sessionId, text } = args[0];
+			log.info(`voice.speak RPC → session=${sessionId}, text=${text?.slice(0, 50) ?? "(audio)"}...`);
+			if (!text) throw new Error("voice.speak requires text");
+			return await voiceApi("POST", "/api/speak", {
+				botId: sessionId,
+				text
+			});
+		});
+		log.info("Registered gateway RPC method: voice.speak");
+		api.on("session_start", async (...eventArgs) => {
+			const key = eventArgs[0].sessionKey;
+			if (!key) return;
+			if (!(key.includes("voice-discord") || key.includes("voice-twilio") || key.includes("voice-recall"))) return;
+			log.info(`Voice session starting: ${key}`);
+			const discordMatch = /voice-discord:(\d+):(\d+)/.exec(key);
+			if (discordMatch) {
+				const [, guildId, channelId] = discordMatch;
+				try {
+					const result = await voiceApi("POST", "/api/discord/join", {
+						guildId,
+						channelId
+					});
+					linkSession(key, result.sessionId);
+					log.info(`Auto-joined Discord voice for session ${key} → ${String(result.sessionId)}`);
+				} catch (err) {
+					log.error(`Failed to auto-join Discord voice: ${err.message}`);
+				}
+			}
+		}, { priority: 50 });
+		api.on("session_end", async (...eventArgs) => {
+			const key = eventArgs[0].sessionKey;
+			if (!key) return;
+			const voiceId = sessionKeyToVoiceId.get(key);
+			if (!voiceId) return;
+			log.info(`Voice session ending: ${key} → ${voiceId}`);
+			try {
+				await voiceApi("POST", `/api/leave/${encodeURIComponent(voiceId)}`);
+			} catch (err) {
+				log.error(`Error leaving voice on session end: ${err.message}`);
+			}
+			unlinkSession(key);
+		});
+		api.on("message_received", (...eventArgs) => {
+			const event = eventArgs[0];
+			if (eventArgs[1].channelId.includes("voice")) log.debug(`Voice-related message from ${event.from}: ${event.content.slice(0, 100)}`);
+		});
+		api.on("before_tool_call", async (...eventArgs) => {
+			const event = eventArgs[0];
+			const ctx = eventArgs[1];
+			if (voiceToolNames.has(event.toolName) && !event.params.sessionId && ctx.sessionKey) {
+				const voiceId = await findVoiceSessionForAgent(ctx.sessionKey);
+				if (voiceId) event.params.sessionId = voiceId;
+			}
+		}, { priority: 50 });
+		log.info("Alfe Voice plugin activated");
+	},
+	deactivate(api) {
+		globalThis.__voiceGatewayActivated = false;
+		const log = api.logger;
+		log.info("Alfe Voice plugin deactivating...");
+		if (daemonIpcClient) {
+			try {
+				daemonIpcClient.stop();
+				log.info("Disconnected from Alfe daemon");
+			} catch (err) {
+				log.debug(`Error disconnecting from daemon: ${err.message}`);
+			}
+			daemonIpcClient = null;
+		}
+		log.info("Alfe Voice plugin deactivated");
+	}
+};
+//#endregion
+export { plugin as default };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@alfe.ai/openclaw-voice",
+  "version": "0.0.1",
+  "description": "OpenClaw voice plugin for Alfe — Discord audio, Twilio, Recall.ai",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/plugin.js"
+    ]
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.48"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}