@alfe.ai/openclaw-voice 0.1.15 → 0.2.0

package/README.md

@@ -1,54 +1,37 @@
-# packages/openclaw-voice (`@alfe.ai/openclaw-voice`)
+# `@alfe.ai/openclaw-voice`
 
-OpenClaw voice plugin for Alfe — Discord audio, Twilio phone calls, and meeting bots.
+OpenClaw tools for Alfe's agent-authenticated one-shot voice endpoints.
 
-## What It Does
+The plugin registers two tools:
 
-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.
+- `voice_tts` converts 1–5000 characters to a new workspace-relative WAV or
+  raw PCM file.
+- `voice_stt` transcribes a workspace-relative WAV or raw mono 16-bit PCM file
+  of at most 10 MiB.
 
-On activation, the plugin:
+Both tools resolve the agent API key and voice-service URL from
+`@alfe.ai/config`, call through `AgentApiClient`, and leave billing to the
+server. The plugin has no provider credential fields, gateway RPC, daemon
+connection, or channel-specific call controls.
 
-- **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
+File arguments are treated as model-controlled input: real paths must stay
+inside the current workspace, input files must be regular files within the
+size cap, and TTS creates output exclusively without replacing existing files.
 
-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}`.
+Channel voice sessions, calls, barge-in, and streaming audio live in the voice
+service and channel adapters; they are not part of this tool-only package.
 
 ## Development
 
-```bash
-pnpm install
-pnpm --filter @alfe.ai/openclaw-voice build
-```
-
-## Testing
-
 ```bash
 pnpm --filter @alfe.ai/openclaw-voice test
+pnpm --filter @alfe.ai/openclaw-voice lint
+pnpm --filter @alfe.ai/openclaw-voice build
 ```
 
-## Dependencies
-
-- **voice-service** — core voice logic (TTS, audio pipeline, Discord/Twilio adapters)
-- **@alfe.ai/openclaw** — OpenClaw runtime plugin API
+See [`DEVELOPING.md`](DEVELOPING.md) for the file-I/O and runtime contracts.
 
 ## Links
 
-- 🌐 Website: <https://alfe.ai>
-- 📚 Docs: <https://docs.alfe.ai>
+- [Alfe](https://alfe.ai)
+- [Documentation](https://docs.alfe.ai)

package/dist/plugin.d.cts

@@ -3,16 +3,6 @@
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/tools.d.ts
-/**
- * Tool-definition helpers — the `defineTool` / `ok` / `errResult` trio that
- * was copy-pasted across 8 plugins (identity, google, teams, mobile,
- * whatsapp, voice, chat a2a-tools, base openclaw).
- *
- * Error handling is standardized on the openclaw-google variant — the only
- * copy that survived non-`Error` throws (`e instanceof Error ? e.message :
- * "Unknown error"`). The other copies did `(e as Error).message`, which
- * crashes the tool executor when a handler throws a string/object.
- */
 /** Shape returned to OpenClaw from a tool `execute`. */
 interface ToolResult {
   content: {
@@ -20,15 +10,8 @@ interface ToolResult {
     text: string;
   }[];
   details: unknown;
+  isError?: boolean;
 }
-/**
- * An OpenClaw tool definition.
- *
- * `parameters` is generic because the fleet is split between TypeBox
- * `TSchema` schemas (identity/google/teams/mobile/whatsapp) and plain
- * JSON-Schema objects (chat a2a-tools). Instantiate with whichever schema
- * type the plugin uses — the kit itself has no schema dependency.
- */
 interface ToolDef<TParameters = unknown> {
   name: string;
   description: string;
@@ -36,7 +19,7 @@ interface ToolDef<TParameters = unknown> {
   parameters: TParameters;
   execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
 }
-/** Wrap a successful handler result in the OpenClaw tool-result envelope. */
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
 //#endregion
 //#region src/plugin.d.ts
 
@@ -46,43 +29,9 @@ interface Logger {
   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 PluginServiceContext {
-  config: Record<string, unknown>;
-  workspaceDir?: string;
-  stateDir: string;
-  logger: Logger;
-}
 interface OpenClawPluginApi {
   logger: Logger;
-  registrationMode?: 'full' | 'setup-only' | 'setup-runtime' | 'cli-metadata';
-  config?: OpenClawConfig;
   registerTool(tool: ToolDef): void;
-  registerGatewayMethod(name: string, handler: (...args: unknown[]) => Promise<unknown>): void;
-  registerService(service: {
-    id: string;
-    start: (ctx: PluginServiceContext) => void | Promise<void>;
-    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
-  }): void;
-  on(event: string, handler: (...args: unknown[]) => void | Promise<void>, options?: {
-    priority?: number;
-  }): void;
 }
 declare const plugin: {
   id: string;

package/dist/plugin.d.ts

@@ -3,16 +3,6 @@
 //# sourceMappingURL=types.d.ts.map
 //#endregion
 //#region src/tools.d.ts
-/**
- * Tool-definition helpers — the `defineTool` / `ok` / `errResult` trio that
- * was copy-pasted across 8 plugins (identity, google, teams, mobile,
- * whatsapp, voice, chat a2a-tools, base openclaw).
- *
- * Error handling is standardized on the openclaw-google variant — the only
- * copy that survived non-`Error` throws (`e instanceof Error ? e.message :
- * "Unknown error"`). The other copies did `(e as Error).message`, which
- * crashes the tool executor when a handler throws a string/object.
- */
 /** Shape returned to OpenClaw from a tool `execute`. */
 interface ToolResult {
   content: {
@@ -20,15 +10,8 @@ interface ToolResult {
     text: string;
   }[];
   details: unknown;
+  isError?: boolean;
 }
-/**
- * An OpenClaw tool definition.
- *
- * `parameters` is generic because the fleet is split between TypeBox
- * `TSchema` schemas (identity/google/teams/mobile/whatsapp) and plain
- * JSON-Schema objects (chat a2a-tools). Instantiate with whichever schema
- * type the plugin uses — the kit itself has no schema dependency.
- */
 interface ToolDef<TParameters = unknown> {
   name: string;
   description: string;
@@ -36,7 +19,7 @@ interface ToolDef<TParameters = unknown> {
   parameters: TParameters;
   execute: (toolCallId: string, params: Record<string, unknown>) => Promise<ToolResult>;
 }
-/** Wrap a successful handler result in the OpenClaw tool-result envelope. */
+/** Deliberately model-safe validation/usage failure. Other exceptions stay private. */
 //#endregion
 //#region src/plugin.d.ts
 
@@ -46,43 +29,9 @@ interface Logger {
   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 PluginServiceContext {
-  config: Record<string, unknown>;
-  workspaceDir?: string;
-  stateDir: string;
-  logger: Logger;
-}
 interface OpenClawPluginApi {
   logger: Logger;
-  registrationMode?: 'full' | 'setup-only' | 'setup-runtime' | 'cli-metadata';
-  config?: OpenClawConfig;
   registerTool(tool: ToolDef): void;
-  registerGatewayMethod(name: string, handler: (...args: unknown[]) => Promise<unknown>): void;
-  registerService(service: {
-    id: string;
-    start: (ctx: PluginServiceContext) => void | Promise<void>;
-    stop?: (ctx: PluginServiceContext) => void | Promise<void>;
-  }): void;
-  on(event: string, handler: (...args: unknown[]) => void | Promise<void>, options?: {
-    priority?: number;
-  }): void;
 }
 declare const plugin: {
   id: string;

package/dist/plugin2.cjs

@@ -2,12 +2,31 @@ let _sinclair_typebox = require("@sinclair/typebox");
 let _alfe_ai_config = require("@alfe.ai/config");
 let _alfe_ai_agent_api_client = require("@alfe.ai/agent-api-client");
 let _alfe_ai_openclaw_plugin_kit = require("@alfe.ai/openclaw-plugin-kit");
+let node_module = require("node:module");
+let node_fs = require("node:fs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
-let node_module = require("node:module");
 //#region src/audio.ts
+const MAX_WAV_PCM_BYTES = 4294967259;
+const SUPPORTED_BIT_DEPTHS = new Set([
+	8,
+	16,
+	24,
+	32
+]);
+function validatePcmFraming(framing, pcmLength) {
+	const { sampleRate, channels, bitDepth } = framing;
+	if (!Number.isInteger(sampleRate) || sampleRate < 8e3 || sampleRate > 384e3) throw new Error("WAV sample rate must be an integer between 8000 and 384000 Hz.");
+	if (!Number.isInteger(channels) || channels < 1 || channels > 32) throw new Error("WAV channel count must be an integer between 1 and 32.");
+	if (!SUPPORTED_BIT_DEPTHS.has(bitDepth)) throw new Error("WAV bit depth must be one of 8, 16, 24, or 32.");
+	const blockAlign = channels * (bitDepth / 8);
+	if (pcmLength % blockAlign !== 0) throw new Error("PCM byte length must contain a whole number of sample frames.");
+	if (pcmLength > MAX_WAV_PCM_BYTES) throw new Error("PCM payload is too large for a RIFF/WAV container.");
+	if (sampleRate * blockAlign > 4294967295) throw new Error("WAV byte rate exceeds the RIFF field limit.");
+}
 /** Prepend a canonical 44-byte PCM WAV header to raw PCM samples. */
 function pcmToWav(pcm, framing) {
+	validatePcmFraming(framing, pcm.length);
 	const { sampleRate, channels, bitDepth } = framing;
 	const blockAlign = channels * (bitDepth / 8);
 	const byteRate = sampleRate * blockAlign;
@@ -28,35 +47,59 @@ function pcmToWav(pcm, framing) {
 	return Buffer.concat([header, pcm]);
 }
 /**
-* Parse a WAV buffer into its PCM payload + framing. Returns `null` when the
-* buffer is not a RIFF/WAVE file (caller should then treat the bytes as raw
-* PCM). Walks the chunk list so it tolerates `fmt `/`data` ordering, extra
-* chunks (e.g. `LIST`/`fact`), and word-alignment padding.
+* Parse a WAV buffer into its PCM payload + framing. Returns `null` only when
+* the buffer is not RIFF data (caller may then treat it as raw PCM). A RIFF
+* buffer that claims to be WAV but is truncated, unsupported, or internally
+* inconsistent throws instead of silently uploading container bytes as PCM.
 */
 function parseWav(buf) {
-	if (buf.length < 44) return null;
-	if (buf.toString("ascii", 0, 4) !== "RIFF") return null;
-	if (buf.toString("ascii", 8, 12) !== "WAVE") return null;
+	if (buf.length < 4 || buf.toString("ascii", 0, 4) !== "RIFF") return null;
+	if (buf.length < 12) throw new Error("Malformed WAV: truncated RIFF header.");
+	if (buf.toString("ascii", 8, 12) !== "WAVE") throw new Error("Unsupported RIFF container: expected WAVE.");
+	const declaredEnd = buf.readUInt32LE(4) + 8;
+	if (declaredEnd !== buf.length) throw new Error("Malformed WAV: RIFF size does not match the file length.");
 	let sampleRate = 0;
 	let channels = 0;
 	let bitDepth = 0;
 	let pcm = null;
+	let blockAlign = 0;
+	let byteRate = 0;
+	let sawFmt = false;
+	let sawData = false;
 	let offset = 12;
-	while (offset + 8 <= buf.length) {
+	while (offset < declaredEnd) {
+		if (offset + 8 > declaredEnd) throw new Error("Malformed WAV: truncated chunk header.");
 		const chunkId = buf.toString("ascii", offset, offset + 4);
 		const chunkSize = buf.readUInt32LE(offset + 4);
 		const bodyStart = offset + 8;
-		if (chunkId === "fmt " && bodyStart + 16 <= buf.length) {
+		const bodyEnd = bodyStart + chunkSize;
+		const nextOffset = bodyEnd + chunkSize % 2;
+		if (bodyEnd > declaredEnd || nextOffset > declaredEnd) throw new Error(`Malformed WAV: truncated ${chunkId} chunk.`);
+		if (chunkId === "fmt ") {
+			if (sawFmt) throw new Error("Malformed WAV: duplicate fmt chunk.");
+			if (chunkSize < 16) throw new Error("Malformed WAV: fmt chunk is too short.");
+			if (buf.readUInt16LE(bodyStart) !== 1) throw new Error("Unsupported WAV encoding: only integer PCM is accepted.");
 			channels = buf.readUInt16LE(bodyStart + 2);
 			sampleRate = buf.readUInt32LE(bodyStart + 4);
+			byteRate = buf.readUInt32LE(bodyStart + 8);
+			blockAlign = buf.readUInt16LE(bodyStart + 12);
 			bitDepth = buf.readUInt16LE(bodyStart + 14);
+			sawFmt = true;
 		} else if (chunkId === "data") {
-			const end = Math.min(bodyStart + chunkSize, buf.length);
-			pcm = buf.subarray(bodyStart, end);
+			if (sawData) throw new Error("Malformed WAV: duplicate data chunk.");
+			pcm = buf.subarray(bodyStart, bodyEnd);
+			sawData = true;
 		}
-		offset = bodyStart + chunkSize + chunkSize % 2;
+		offset = nextOffset;
 	}
-	if (!pcm || sampleRate === 0 || channels === 0 || bitDepth === 0) return null;
+	if (!sawFmt || !sawData || pcm === null) throw new Error("Malformed WAV: both fmt and data chunks are required.");
+	validatePcmFraming({
+		sampleRate,
+		channels,
+		bitDepth
+	}, pcm.length);
+	const expectedBlockAlign = channels * (bitDepth / 8);
+	if (blockAlign !== expectedBlockAlign || byteRate !== sampleRate * expectedBlockAlign) throw new Error("Malformed WAV: byte rate or block alignment is inconsistent with its framing.");
 	return {
 		pcm,
 		sampleRate,
@@ -65,6 +108,83 @@ function parseWav(buf) {
 	};
 }
 //#endregion
+//#region src/workspace-files.ts
+const MAX_TOOL_PATH_LENGTH = 1024;
+function isWithin(root, candidate) {
+	const rel = (0, node_path.relative)(root, candidate);
+	return rel === "" || !(0, node_path.isAbsolute)(rel) && rel !== ".." && !rel.startsWith(`..${node_path.sep}`);
+}
+function assertRelativeToolPath(input, label) {
+	if (input.length === 0) throw new Error(`${label} must not be empty.`);
+	if (input.length > MAX_TOOL_PATH_LENGTH) throw new Error(`${label} is too long (maximum ${String(MAX_TOOL_PATH_LENGTH)} characters).`);
+	if (input.includes("\0")) throw new Error(`${label} contains a null byte.`);
+	if ((0, node_path.isAbsolute)(input) || /^[A-Za-z]:[\\/]/u.test(input) || input.startsWith("\\\\")) throw new Error(`${label} must be relative to the workspace.`);
+	if (input.split(/[\\/]/u).includes("..")) throw new Error(`${label} must not contain parent-directory traversal.`);
+}
+async function workspaceRoot() {
+	return (0, node_fs_promises.realpath)(process.cwd());
+}
+async function readWorkspaceFile(input, maxBytes) {
+	assertRelativeToolPath(input, "Path");
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error("Maximum file size must be a positive safe integer.");
+	const root = await workspaceRoot();
+	const lexicalPath = (0, node_path.resolve)(root, input);
+	if (!isWithin(root, lexicalPath)) throw new Error("Path escapes the workspace.");
+	const absolutePath = await (0, node_fs_promises.realpath)(lexicalPath);
+	if (!isWithin(root, absolutePath)) throw new Error("Path resolves outside the workspace.");
+	const handle = await (0, node_fs_promises.open)(absolutePath, node_fs.constants.O_RDONLY | node_fs.constants.O_NOFOLLOW);
+	try {
+		const before = await handle.stat();
+		if (!before.isFile()) throw new Error("Path must refer to a regular file.");
+		if (before.size > maxBytes) throw new Error(`File is too large (maximum ${String(maxBytes)} bytes).`);
+		const data = await handle.readFile();
+		const after = await handle.stat();
+		if (data.length > maxBytes || after.size > maxBytes) throw new Error(`File is too large (maximum ${String(maxBytes)} bytes).`);
+		return {
+			absolutePath,
+			data
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function resolveWorkspaceOutputPath(input) {
+	assertRelativeToolPath(input, "Output path");
+	const root = await workspaceRoot();
+	const lexicalPath = (0, node_path.resolve)(root, input);
+	if (!isWithin(root, lexicalPath)) throw new Error("Output path escapes the workspace.");
+	const parent = await (0, node_fs_promises.realpath)((0, node_path.dirname)(lexicalPath));
+	if (!isWithin(root, parent)) throw new Error("Output path resolves outside the workspace.");
+	const absolutePath = (0, node_path.join)(parent, (0, node_path.basename)(lexicalPath));
+	try {
+		await (0, node_fs_promises.lstat)(absolutePath);
+		throw new Error(`Refusing to overwrite existing workspace file: ${input}`);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	return absolutePath;
+}
+async function writeWorkspaceFileExclusive(input, data) {
+	const absolutePath = await resolveWorkspaceOutputPath(input);
+	let handle;
+	try {
+		handle = await (0, node_fs_promises.open)(absolutePath, "wx", 384);
+	} catch (error) {
+		if (error.code === "EEXIST") throw new Error(`Refusing to overwrite existing workspace file: ${input}`);
+		throw error;
+	}
+	let completed = false;
+	try {
+		await handle.writeFile(data);
+		await handle.sync();
+		completed = true;
+		return absolutePath;
+	} finally {
+		await handle.close();
+		if (!completed) await (0, node_fs_promises.unlink)(absolutePath).catch(() => void 0);
+	}
+}
+//#endregion
 //#region src/plugin.ts
 /**
 * @alfe/voice-plugin — OpenClaw native plugin
@@ -79,7 +199,9 @@ function parseWav(buf) {
 * This plugin provides:
 *   - voice_tts tool — text → audio file via POST /voice/tts (agent-authed)
 *   - voice_stt tool — audio file → transcript via POST /voice/stt (agent-authed)
-*   - voice.speak RPC — legacy gateway RPC (reads plugin config; vestigial)
+*
+* The plugin is intentionally tool-only. It has no daemon connection,
+* gateway RPC, message hook, or plugin-config credential path.
 *
 * voice_hangup / voice_transfer / voice_dtmf were removed deliberately — they
 * threw unconditionally ("requires a channel service"), which poisons the
@@ -92,32 +214,10 @@ function parseWav(buf) {
 * or hit localhost.
 */
 const pkg = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href)("../package.json");
-const VOICE_CAPABILITIES = [
-	"voice.call",
-	"voice.answer",
-	"voice.dtmf",
-	"voice.hangup"
-];
-const VOICE_ACTIVATION_KEY = (0, _alfe_ai_openclaw_plugin_kit.getActivationKey)("voice");
-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;
+const MAX_AUDIO_FILE_BYTES = 10 * 1024 * 1024;
+const MAX_TTS_RESPONSE_BYTES = 32 * 1024 * 1024;
+const VOICE_ID_PATTERN = "^[A-Za-z0-9_-]{1,200}$";
+const VOICE_ID_REGEX = /^[A-Za-z0-9_-]{1,200}$/u;
 let voiceClient = null;
 function getVoiceClient() {
 	if (voiceClient) return voiceClient;
@@ -128,39 +228,54 @@ function getVoiceClient() {
 	});
 	return voiceClient;
 }
-/** Resolve a tool-supplied path against the agent's working directory. */
-function resolveWorkspacePath(p) {
-	return (0, node_path.isAbsolute)(p) ? p : (0, node_path.resolve)(process.cwd(), p);
-}
 const voiceTools = [(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
 	name: "voice_tts",
 	description: "Convert text to speech using the Alfe voice service (ElevenLabs). Writes a playable audio file to the workspace and returns its path. Billed per character to your tenant credit pool.",
 	parameters: _sinclair_typebox.Type.Object({
-		text: _sinclair_typebox.Type.String({ description: "Text to synthesize (1–5000 characters)." }),
-		outputPath: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "Where to write the audio file (absolute, or relative to the working directory). Defaults to alfe-tts-<timestamp>.wav in the working directory." })),
+		text: _sinclair_typebox.Type.String({
+			minLength: 1,
+			maxLength: 5e3,
+			description: "Text to synthesize (1–5000 characters)."
+		}),
+		outputPath: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({
+			minLength: 1,
+			maxLength: 1024,
+			description: "New workspace-relative audio file to create. Existing files are never overwritten. Defaults to alfe-tts-<timestamp>.wav."
+		})),
 		format: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.Union([_sinclair_typebox.Type.Literal("wav"), _sinclair_typebox.Type.Literal("pcm")], { description: "Output container. 'wav' (default) is a playable file; 'pcm' is headerless 24kHz/mono/16-bit raw PCM." })),
-		voiceId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({ description: "ElevenLabs voice ID. Platform default when omitted." })),
+		voiceId: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.String({
+			pattern: VOICE_ID_PATTERN,
+			description: "ElevenLabs voice ID. Platform default when omitted."
+		})),
 		model: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.Union([_sinclair_typebox.Type.Literal("eleven_turbo_v2_5"), _sinclair_typebox.Type.Literal("eleven_multilingual_v2")], { description: "TTS model. eleven_turbo_v2_5 (lower latency) when omitted." }))
 	}),
 	handler: async (params) => {
-		const text = params.text;
+		const text = params.text.trim();
+		if (text.length < 1 || text.length > 5e3) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("voice_tts text must contain 1–5000 characters.");
+		const voiceId = params.voiceId;
+		if (voiceId !== void 0 && !VOICE_ID_REGEX.test(voiceId)) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("voice_tts voiceId contains unsupported characters.");
 		const format = params.format ?? "wav";
+		const outputPath = params.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
+		await resolveWorkspaceOutputPath(outputPath);
 		const result = await getVoiceClient().tts({
 			text,
-			voiceId: params.voiceId,
+			voiceId,
 			model: params.model
 		});
+		if (result.audio.length === 0 || result.audio.length > MAX_TTS_RESPONSE_BYTES) throw new Error(`voice_tts returned an invalid audio payload size (${String(result.audio.length)} bytes).`);
+		validatePcmFraming({
+			sampleRate: result.sampleRate,
+			channels: result.channels,
+			bitDepth: result.bitDepth
+		}, result.audio.length);
 		const bytes = format === "wav" ? pcmToWav(result.audio, {
 			sampleRate: result.sampleRate,
 			channels: result.channels,
 			bitDepth: result.bitDepth
 		}) : result.audio;
-		const outputPath = params.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
-		const absolutePath = resolveWorkspacePath(outputPath);
-		await (0, node_fs_promises.writeFile)(absolutePath, bytes);
 		return {
 			path: outputPath,
-			absolutePath,
+			absolutePath: await writeWorkspaceFileExclusive(outputPath, bytes),
 			format,
 			sampleRate: result.sampleRate,
 			channels: result.channels,
@@ -173,22 +288,33 @@ const voiceTools = [(0, _alfe_ai_openclaw_plugin_kit.defineTool)({
 	name: "voice_stt",
 	description: "Transcribe an audio file to text using the Alfe voice service (Deepgram). Accepts a WAV file or headerless mono 16-bit PCM. Billed per audio-second to your tenant credit pool.",
 	parameters: _sinclair_typebox.Type.Object({
-		path: _sinclair_typebox.Type.String({ description: "Path to the audio file (absolute, or relative to the working directory). WAV or raw linear16 mono PCM." }),
-		sampleRate: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.Number({ description: "Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000." }))
+		path: _sinclair_typebox.Type.String({
+			minLength: 1,
+			maxLength: 1024,
+			description: "Workspace-relative path to a WAV or raw linear16 mono PCM file (maximum 10 MiB)."
+		}),
+		sampleRate: _sinclair_typebox.Type.Optional(_sinclair_typebox.Type.Number({
+			minimum: 8e3,
+			maximum: 48e3,
+			multipleOf: 1,
+			description: "Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000."
+		}))
 	}),
 	handler: async (params) => {
-		const raw = await (0, node_fs_promises.readFile)(resolveWorkspacePath(params.path));
+		const { data: raw } = await readWorkspaceFile(params.path, MAX_AUDIO_FILE_BYTES);
 		const wav = parseWav(raw);
 		let audio;
 		let sampleRate;
 		if (wav) {
-			if (wav.bitDepth !== 16 || wav.channels !== 1) throw new Error(`voice_stt needs 16-bit mono audio; got ${String(wav.bitDepth)}-bit / ${String(wav.channels)}-channel WAV. Re-export as 16-bit mono.`);
+			if (wav.bitDepth !== 16 || wav.channels !== 1) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)(`voice_stt needs 16-bit mono audio; got ${String(wav.bitDepth)}-bit / ${String(wav.channels)}-channel WAV. Re-export as 16-bit mono.`);
 			audio = wav.pcm;
 			sampleRate = wav.sampleRate;
 		} else {
 			audio = raw;
 			sampleRate = params.sampleRate ?? 24e3;
 		}
+		if (!Number.isInteger(sampleRate) || sampleRate < 8e3 || sampleRate > 48e3) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("voice_stt sampleRate must be an integer between 8000 and 48000 Hz.");
+		if (audio.length === 0 || audio.length % 2 !== 0) throw (0, _alfe_ai_openclaw_plugin_kit.publicToolError)("voice_stt needs non-empty 16-bit PCM with an even byte length.");
 		return getVoiceClient().stt({
 			audio,
 			sampleRate
@@ -205,77 +331,12 @@ const plugin = {
 		const log = api.logger;
 		for (const tool of voiceTools) api.registerTool(tool);
 		log.info(`Registered ${String(voiceTools.length)} voice tools: ${voiceTools.map((t) => t.name).join(", ")}`);
-		const fullConfig = api.config ?? {};
-		const pluginConfig = fullConfig.plugins?.entries?.["@alfe.ai/openclaw-voice"]?.config ?? fullConfig.plugins?.entries?.["voice-gateway"]?.config ?? {};
-		const startVoiceService = () => {
-			(0, _alfe_ai_openclaw_plugin_kit.guardedStart)(VOICE_ACTIVATION_KEY, log, () => {
-				log.info("Alfe Voice plugin activating...");
-				voiceServiceUrl = pluginConfig.voiceServiceUrl ?? `http://localhost:${String(pluginConfig.voiceServicePort ?? "3100")}`;
-				voiceServiceApiKey = pluginConfig.voiceServiceApiKey ?? "";
-				log.info(`Voice service: ${voiceServiceUrl}`);
-				let alfeConfig = null;
-				try {
-					alfeConfig = (0, _alfe_ai_config.resolveConfig)();
-				} catch {}
-				(0, _alfe_ai_openclaw_plugin_kit.connectToDaemon)(pluginConfig.daemonSocket ?? alfeConfig?.socketPath ?? _alfe_ai_config.DEFAULT_SOCKET_PATH, log, {
-					pluginId: "@alfe.ai/openclaw-voice",
-					capabilities: VOICE_CAPABILITIES,
-					standaloneNote: "Alfe daemon not available — voice plugin running standalone"
-				}).then((client) => {
-					daemonIpcClient = client;
-				}).catch((err) => {
-					log.debug(`Daemon connect failed: ${err.message}`);
-				});
-			});
-		};
-		const stopVoiceService = () => {
-			if (daemonIpcClient) {
-				try {
-					daemonIpcClient.stop();
-					log.info("Disconnected from Alfe daemon");
-				} catch (err) {
-					log.debug(`Error disconnecting from daemon: ${err.message}`);
-				}
-				daemonIpcClient = null;
-			}
-			(0, _alfe_ai_openclaw_plugin_kit.resetActivation)(VOICE_ACTIVATION_KEY);
-			log.info("Alfe Voice plugin deactivated");
-		};
-		api.registerGatewayMethod("voice.speak", async (...args) => {
-			const { text } = args[0];
-			log.info(`voice.speak RPC → text=${text?.slice(0, 50) ?? "(none)"}...`);
-			if (!text) throw new Error("voice.speak requires text");
-			return await voiceApi("POST", "/voice/tts", { text });
-		});
-		log.info("Registered gateway RPC method: voice.speak");
-		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.registerService({
-			id: "alfe-voice-daemon",
-			start: () => {
-				startVoiceService();
-			},
-			stop: () => {
-				stopVoiceService();
-			}
-		});
 		log.info("Alfe Voice plugin activated");
 	},
 	deactivate(api) {
 		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;
-		}
-		(0, _alfe_ai_openclaw_plugin_kit.resetActivation)(VOICE_ACTIVATION_KEY);
+		voiceClient = null;
 		log.info("Alfe Voice plugin deactivated");
 	}
 };

package/dist/plugin2.js

@@ -1,13 +1,32 @@
 import { createRequire } from "node:module";
 import { Type } from "@sinclair/typebox";
-import { DEFAULT_SOCKET_PATH, resolveConfig } from "@alfe.ai/config";
+import { resolveConfig } from "@alfe.ai/config";
 import { AgentApiClient, installToolErrorCapture } from "@alfe.ai/agent-api-client";
-import { connectToDaemon, defineTool, getActivationKey, guardedStart, resetActivation } from "@alfe.ai/openclaw-plugin-kit";
-import { readFile, writeFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
+import { defineTool, publicToolError } from "@alfe.ai/openclaw-plugin-kit";
+import { constants } from "node:fs";
+import { lstat, open, realpath, unlink } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 //#region src/audio.ts
+const MAX_WAV_PCM_BYTES = 4294967259;
+const SUPPORTED_BIT_DEPTHS = new Set([
+	8,
+	16,
+	24,
+	32
+]);
+function validatePcmFraming(framing, pcmLength) {
+	const { sampleRate, channels, bitDepth } = framing;
+	if (!Number.isInteger(sampleRate) || sampleRate < 8e3 || sampleRate > 384e3) throw new Error("WAV sample rate must be an integer between 8000 and 384000 Hz.");
+	if (!Number.isInteger(channels) || channels < 1 || channels > 32) throw new Error("WAV channel count must be an integer between 1 and 32.");
+	if (!SUPPORTED_BIT_DEPTHS.has(bitDepth)) throw new Error("WAV bit depth must be one of 8, 16, 24, or 32.");
+	const blockAlign = channels * (bitDepth / 8);
+	if (pcmLength % blockAlign !== 0) throw new Error("PCM byte length must contain a whole number of sample frames.");
+	if (pcmLength > MAX_WAV_PCM_BYTES) throw new Error("PCM payload is too large for a RIFF/WAV container.");
+	if (sampleRate * blockAlign > 4294967295) throw new Error("WAV byte rate exceeds the RIFF field limit.");
+}
 /** Prepend a canonical 44-byte PCM WAV header to raw PCM samples. */
 function pcmToWav(pcm, framing) {
+	validatePcmFraming(framing, pcm.length);
 	const { sampleRate, channels, bitDepth } = framing;
 	const blockAlign = channels * (bitDepth / 8);
 	const byteRate = sampleRate * blockAlign;
@@ -28,35 +47,59 @@ function pcmToWav(pcm, framing) {
 	return Buffer.concat([header, pcm]);
 }
 /**
-* Parse a WAV buffer into its PCM payload + framing. Returns `null` when the
-* buffer is not a RIFF/WAVE file (caller should then treat the bytes as raw
-* PCM). Walks the chunk list so it tolerates `fmt `/`data` ordering, extra
-* chunks (e.g. `LIST`/`fact`), and word-alignment padding.
+* Parse a WAV buffer into its PCM payload + framing. Returns `null` only when
+* the buffer is not RIFF data (caller may then treat it as raw PCM). A RIFF
+* buffer that claims to be WAV but is truncated, unsupported, or internally
+* inconsistent throws instead of silently uploading container bytes as PCM.
 */
 function parseWav(buf) {
-	if (buf.length < 44) return null;
-	if (buf.toString("ascii", 0, 4) !== "RIFF") return null;
-	if (buf.toString("ascii", 8, 12) !== "WAVE") return null;
+	if (buf.length < 4 || buf.toString("ascii", 0, 4) !== "RIFF") return null;
+	if (buf.length < 12) throw new Error("Malformed WAV: truncated RIFF header.");
+	if (buf.toString("ascii", 8, 12) !== "WAVE") throw new Error("Unsupported RIFF container: expected WAVE.");
+	const declaredEnd = buf.readUInt32LE(4) + 8;
+	if (declaredEnd !== buf.length) throw new Error("Malformed WAV: RIFF size does not match the file length.");
 	let sampleRate = 0;
 	let channels = 0;
 	let bitDepth = 0;
 	let pcm = null;
+	let blockAlign = 0;
+	let byteRate = 0;
+	let sawFmt = false;
+	let sawData = false;
 	let offset = 12;
-	while (offset + 8 <= buf.length) {
+	while (offset < declaredEnd) {
+		if (offset + 8 > declaredEnd) throw new Error("Malformed WAV: truncated chunk header.");
 		const chunkId = buf.toString("ascii", offset, offset + 4);
 		const chunkSize = buf.readUInt32LE(offset + 4);
 		const bodyStart = offset + 8;
-		if (chunkId === "fmt " && bodyStart + 16 <= buf.length) {
+		const bodyEnd = bodyStart + chunkSize;
+		const nextOffset = bodyEnd + chunkSize % 2;
+		if (bodyEnd > declaredEnd || nextOffset > declaredEnd) throw new Error(`Malformed WAV: truncated ${chunkId} chunk.`);
+		if (chunkId === "fmt ") {
+			if (sawFmt) throw new Error("Malformed WAV: duplicate fmt chunk.");
+			if (chunkSize < 16) throw new Error("Malformed WAV: fmt chunk is too short.");
+			if (buf.readUInt16LE(bodyStart) !== 1) throw new Error("Unsupported WAV encoding: only integer PCM is accepted.");
 			channels = buf.readUInt16LE(bodyStart + 2);
 			sampleRate = buf.readUInt32LE(bodyStart + 4);
+			byteRate = buf.readUInt32LE(bodyStart + 8);
+			blockAlign = buf.readUInt16LE(bodyStart + 12);
 			bitDepth = buf.readUInt16LE(bodyStart + 14);
+			sawFmt = true;
 		} else if (chunkId === "data") {
-			const end = Math.min(bodyStart + chunkSize, buf.length);
-			pcm = buf.subarray(bodyStart, end);
+			if (sawData) throw new Error("Malformed WAV: duplicate data chunk.");
+			pcm = buf.subarray(bodyStart, bodyEnd);
+			sawData = true;
 		}
-		offset = bodyStart + chunkSize + chunkSize % 2;
+		offset = nextOffset;
 	}
-	if (!pcm || sampleRate === 0 || channels === 0 || bitDepth === 0) return null;
+	if (!sawFmt || !sawData || pcm === null) throw new Error("Malformed WAV: both fmt and data chunks are required.");
+	validatePcmFraming({
+		sampleRate,
+		channels,
+		bitDepth
+	}, pcm.length);
+	const expectedBlockAlign = channels * (bitDepth / 8);
+	if (blockAlign !== expectedBlockAlign || byteRate !== sampleRate * expectedBlockAlign) throw new Error("Malformed WAV: byte rate or block alignment is inconsistent with its framing.");
 	return {
 		pcm,
 		sampleRate,
@@ -65,6 +108,83 @@ function parseWav(buf) {
 	};
 }
 //#endregion
+//#region src/workspace-files.ts
+const MAX_TOOL_PATH_LENGTH = 1024;
+function isWithin(root, candidate) {
+	const rel = relative(root, candidate);
+	return rel === "" || !isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`);
+}
+function assertRelativeToolPath(input, label) {
+	if (input.length === 0) throw new Error(`${label} must not be empty.`);
+	if (input.length > MAX_TOOL_PATH_LENGTH) throw new Error(`${label} is too long (maximum ${String(MAX_TOOL_PATH_LENGTH)} characters).`);
+	if (input.includes("\0")) throw new Error(`${label} contains a null byte.`);
+	if (isAbsolute(input) || /^[A-Za-z]:[\\/]/u.test(input) || input.startsWith("\\\\")) throw new Error(`${label} must be relative to the workspace.`);
+	if (input.split(/[\\/]/u).includes("..")) throw new Error(`${label} must not contain parent-directory traversal.`);
+}
+async function workspaceRoot() {
+	return realpath(process.cwd());
+}
+async function readWorkspaceFile(input, maxBytes) {
+	assertRelativeToolPath(input, "Path");
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new Error("Maximum file size must be a positive safe integer.");
+	const root = await workspaceRoot();
+	const lexicalPath = resolve(root, input);
+	if (!isWithin(root, lexicalPath)) throw new Error("Path escapes the workspace.");
+	const absolutePath = await realpath(lexicalPath);
+	if (!isWithin(root, absolutePath)) throw new Error("Path resolves outside the workspace.");
+	const handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+	try {
+		const before = await handle.stat();
+		if (!before.isFile()) throw new Error("Path must refer to a regular file.");
+		if (before.size > maxBytes) throw new Error(`File is too large (maximum ${String(maxBytes)} bytes).`);
+		const data = await handle.readFile();
+		const after = await handle.stat();
+		if (data.length > maxBytes || after.size > maxBytes) throw new Error(`File is too large (maximum ${String(maxBytes)} bytes).`);
+		return {
+			absolutePath,
+			data
+		};
+	} finally {
+		await handle.close();
+	}
+}
+async function resolveWorkspaceOutputPath(input) {
+	assertRelativeToolPath(input, "Output path");
+	const root = await workspaceRoot();
+	const lexicalPath = resolve(root, input);
+	if (!isWithin(root, lexicalPath)) throw new Error("Output path escapes the workspace.");
+	const parent = await realpath(dirname(lexicalPath));
+	if (!isWithin(root, parent)) throw new Error("Output path resolves outside the workspace.");
+	const absolutePath = join(parent, basename(lexicalPath));
+	try {
+		await lstat(absolutePath);
+		throw new Error(`Refusing to overwrite existing workspace file: ${input}`);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+	}
+	return absolutePath;
+}
+async function writeWorkspaceFileExclusive(input, data) {
+	const absolutePath = await resolveWorkspaceOutputPath(input);
+	let handle;
+	try {
+		handle = await open(absolutePath, "wx", 384);
+	} catch (error) {
+		if (error.code === "EEXIST") throw new Error(`Refusing to overwrite existing workspace file: ${input}`);
+		throw error;
+	}
+	let completed = false;
+	try {
+		await handle.writeFile(data);
+		await handle.sync();
+		completed = true;
+		return absolutePath;
+	} finally {
+		await handle.close();
+		if (!completed) await unlink(absolutePath).catch(() => void 0);
+	}
+}
+//#endregion
 //#region src/plugin.ts
 /**
 * @alfe/voice-plugin — OpenClaw native plugin
@@ -79,7 +199,9 @@ function parseWav(buf) {
 * This plugin provides:
 *   - voice_tts tool — text → audio file via POST /voice/tts (agent-authed)
 *   - voice_stt tool — audio file → transcript via POST /voice/stt (agent-authed)
-*   - voice.speak RPC — legacy gateway RPC (reads plugin config; vestigial)
+*
+* The plugin is intentionally tool-only. It has no daemon connection,
+* gateway RPC, message hook, or plugin-config credential path.
 *
 * voice_hangup / voice_transfer / voice_dtmf were removed deliberately — they
 * threw unconditionally ("requires a channel service"), which poisons the
@@ -92,32 +214,10 @@ function parseWav(buf) {
 * or hit localhost.
 */
 const pkg = createRequire(import.meta.url)("../package.json");
-const VOICE_CAPABILITIES = [
-	"voice.call",
-	"voice.answer",
-	"voice.dtmf",
-	"voice.hangup"
-];
-const VOICE_ACTIVATION_KEY = getActivationKey("voice");
-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;
+const MAX_AUDIO_FILE_BYTES = 10 * 1024 * 1024;
+const MAX_TTS_RESPONSE_BYTES = 32 * 1024 * 1024;
+const VOICE_ID_PATTERN = "^[A-Za-z0-9_-]{1,200}$";
+const VOICE_ID_REGEX = /^[A-Za-z0-9_-]{1,200}$/u;
 let voiceClient = null;
 function getVoiceClient() {
 	if (voiceClient) return voiceClient;
@@ -128,39 +228,54 @@ function getVoiceClient() {
 	});
 	return voiceClient;
 }
-/** Resolve a tool-supplied path against the agent's working directory. */
-function resolveWorkspacePath(p) {
-	return isAbsolute(p) ? p : resolve(process.cwd(), p);
-}
 const voiceTools = [defineTool({
 	name: "voice_tts",
 	description: "Convert text to speech using the Alfe voice service (ElevenLabs). Writes a playable audio file to the workspace and returns its path. Billed per character to your tenant credit pool.",
 	parameters: Type.Object({
-		text: Type.String({ description: "Text to synthesize (1–5000 characters)." }),
-		outputPath: Type.Optional(Type.String({ description: "Where to write the audio file (absolute, or relative to the working directory). Defaults to alfe-tts-<timestamp>.wav in the working directory." })),
+		text: Type.String({
+			minLength: 1,
+			maxLength: 5e3,
+			description: "Text to synthesize (1–5000 characters)."
+		}),
+		outputPath: Type.Optional(Type.String({
+			minLength: 1,
+			maxLength: 1024,
+			description: "New workspace-relative audio file to create. Existing files are never overwritten. Defaults to alfe-tts-<timestamp>.wav."
+		})),
 		format: Type.Optional(Type.Union([Type.Literal("wav"), Type.Literal("pcm")], { description: "Output container. 'wav' (default) is a playable file; 'pcm' is headerless 24kHz/mono/16-bit raw PCM." })),
-		voiceId: Type.Optional(Type.String({ description: "ElevenLabs voice ID. Platform default when omitted." })),
+		voiceId: Type.Optional(Type.String({
+			pattern: VOICE_ID_PATTERN,
+			description: "ElevenLabs voice ID. Platform default when omitted."
+		})),
 		model: Type.Optional(Type.Union([Type.Literal("eleven_turbo_v2_5"), Type.Literal("eleven_multilingual_v2")], { description: "TTS model. eleven_turbo_v2_5 (lower latency) when omitted." }))
 	}),
 	handler: async (params) => {
-		const text = params.text;
+		const text = params.text.trim();
+		if (text.length < 1 || text.length > 5e3) throw publicToolError("voice_tts text must contain 1–5000 characters.");
+		const voiceId = params.voiceId;
+		if (voiceId !== void 0 && !VOICE_ID_REGEX.test(voiceId)) throw publicToolError("voice_tts voiceId contains unsupported characters.");
 		const format = params.format ?? "wav";
+		const outputPath = params.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
+		await resolveWorkspaceOutputPath(outputPath);
 		const result = await getVoiceClient().tts({
 			text,
-			voiceId: params.voiceId,
+			voiceId,
 			model: params.model
 		});
+		if (result.audio.length === 0 || result.audio.length > MAX_TTS_RESPONSE_BYTES) throw new Error(`voice_tts returned an invalid audio payload size (${String(result.audio.length)} bytes).`);
+		validatePcmFraming({
+			sampleRate: result.sampleRate,
+			channels: result.channels,
+			bitDepth: result.bitDepth
+		}, result.audio.length);
 		const bytes = format === "wav" ? pcmToWav(result.audio, {
 			sampleRate: result.sampleRate,
 			channels: result.channels,
 			bitDepth: result.bitDepth
 		}) : result.audio;
-		const outputPath = params.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
-		const absolutePath = resolveWorkspacePath(outputPath);
-		await writeFile(absolutePath, bytes);
 		return {
 			path: outputPath,
-			absolutePath,
+			absolutePath: await writeWorkspaceFileExclusive(outputPath, bytes),
 			format,
 			sampleRate: result.sampleRate,
 			channels: result.channels,
@@ -173,22 +288,33 @@ const voiceTools = [defineTool({
 	name: "voice_stt",
 	description: "Transcribe an audio file to text using the Alfe voice service (Deepgram). Accepts a WAV file or headerless mono 16-bit PCM. Billed per audio-second to your tenant credit pool.",
 	parameters: Type.Object({
-		path: Type.String({ description: "Path to the audio file (absolute, or relative to the working directory). WAV or raw linear16 mono PCM." }),
-		sampleRate: Type.Optional(Type.Number({ description: "Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000." }))
+		path: Type.String({
+			minLength: 1,
+			maxLength: 1024,
+			description: "Workspace-relative path to a WAV or raw linear16 mono PCM file (maximum 10 MiB)."
+		}),
+		sampleRate: Type.Optional(Type.Number({
+			minimum: 8e3,
+			maximum: 48e3,
+			multipleOf: 1,
+			description: "Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000."
+		}))
 	}),
 	handler: async (params) => {
-		const raw = await readFile(resolveWorkspacePath(params.path));
+		const { data: raw } = await readWorkspaceFile(params.path, MAX_AUDIO_FILE_BYTES);
 		const wav = parseWav(raw);
 		let audio;
 		let sampleRate;
 		if (wav) {
-			if (wav.bitDepth !== 16 || wav.channels !== 1) throw new Error(`voice_stt needs 16-bit mono audio; got ${String(wav.bitDepth)}-bit / ${String(wav.channels)}-channel WAV. Re-export as 16-bit mono.`);
+			if (wav.bitDepth !== 16 || wav.channels !== 1) throw publicToolError(`voice_stt needs 16-bit mono audio; got ${String(wav.bitDepth)}-bit / ${String(wav.channels)}-channel WAV. Re-export as 16-bit mono.`);
 			audio = wav.pcm;
 			sampleRate = wav.sampleRate;
 		} else {
 			audio = raw;
 			sampleRate = params.sampleRate ?? 24e3;
 		}
+		if (!Number.isInteger(sampleRate) || sampleRate < 8e3 || sampleRate > 48e3) throw publicToolError("voice_stt sampleRate must be an integer between 8000 and 48000 Hz.");
+		if (audio.length === 0 || audio.length % 2 !== 0) throw publicToolError("voice_stt needs non-empty 16-bit PCM with an even byte length.");
 		return getVoiceClient().stt({
 			audio,
 			sampleRate
@@ -205,77 +331,12 @@ const plugin = {
 		const log = api.logger;
 		for (const tool of voiceTools) api.registerTool(tool);
 		log.info(`Registered ${String(voiceTools.length)} voice tools: ${voiceTools.map((t) => t.name).join(", ")}`);
-		const fullConfig = api.config ?? {};
-		const pluginConfig = fullConfig.plugins?.entries?.["@alfe.ai/openclaw-voice"]?.config ?? fullConfig.plugins?.entries?.["voice-gateway"]?.config ?? {};
-		const startVoiceService = () => {
-			guardedStart(VOICE_ACTIVATION_KEY, log, () => {
-				log.info("Alfe Voice plugin activating...");
-				voiceServiceUrl = pluginConfig.voiceServiceUrl ?? `http://localhost:${String(pluginConfig.voiceServicePort ?? "3100")}`;
-				voiceServiceApiKey = pluginConfig.voiceServiceApiKey ?? "";
-				log.info(`Voice service: ${voiceServiceUrl}`);
-				let alfeConfig = null;
-				try {
-					alfeConfig = resolveConfig();
-				} catch {}
-				connectToDaemon(pluginConfig.daemonSocket ?? alfeConfig?.socketPath ?? DEFAULT_SOCKET_PATH, log, {
-					pluginId: "@alfe.ai/openclaw-voice",
-					capabilities: VOICE_CAPABILITIES,
-					standaloneNote: "Alfe daemon not available — voice plugin running standalone"
-				}).then((client) => {
-					daemonIpcClient = client;
-				}).catch((err) => {
-					log.debug(`Daemon connect failed: ${err.message}`);
-				});
-			});
-		};
-		const stopVoiceService = () => {
-			if (daemonIpcClient) {
-				try {
-					daemonIpcClient.stop();
-					log.info("Disconnected from Alfe daemon");
-				} catch (err) {
-					log.debug(`Error disconnecting from daemon: ${err.message}`);
-				}
-				daemonIpcClient = null;
-			}
-			resetActivation(VOICE_ACTIVATION_KEY);
-			log.info("Alfe Voice plugin deactivated");
-		};
-		api.registerGatewayMethod("voice.speak", async (...args) => {
-			const { text } = args[0];
-			log.info(`voice.speak RPC → text=${text?.slice(0, 50) ?? "(none)"}...`);
-			if (!text) throw new Error("voice.speak requires text");
-			return await voiceApi("POST", "/voice/tts", { text });
-		});
-		log.info("Registered gateway RPC method: voice.speak");
-		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.registerService({
-			id: "alfe-voice-daemon",
-			start: () => {
-				startVoiceService();
-			},
-			stop: () => {
-				stopVoiceService();
-			}
-		});
 		log.info("Alfe Voice plugin activated");
 	},
 	deactivate(api) {
 		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;
-		}
-		resetActivation(VOICE_ACTIVATION_KEY);
+		voiceClient = null;
 		log.info("Alfe Voice plugin deactivated");
 	}
 };

package/openclaw.plugin.json

@@ -3,22 +3,13 @@
   "name": "Alfe Voice Plugin",
   "description": "Alfe voice plugin — agent-callable one-shot TTS/STT via the voice service (billed to the tenant credit pool). Channel-specific ops (hangup/transfer/DTMF) are handled by channel services.",
   "entry": "./dist/plugin.js",
-  "activation": { "onStartup": true },
+  "activation": { "onStartup": false },
   "contracts": {
     "tools": ["voice_tts", "voice_stt"]
   },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
-    "properties": {
-      "agentToken": {
-        "type": "string",
-        "description": "Single token for relay authentication and agent identification. Defaults to api_key from ~/.alfe/config.toml if not set."
-      },
-      "relayUrl": {
-        "type": "string",
-        "description": "WebSocket URL of the Fly voice server relay endpoint. Defaults to wss://voice.dev.alfe.ai/gateway"
-      }
-    }
+    "properties": {}
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alfe.ai/openclaw-voice",
-  "version": "0.1.15",
-  "description": "OpenClaw voice plugin for Alfe — Discord audio, Twilio, Recall.ai",
+  "version": "0.2.0",
+  "description": "OpenClaw tools for Alfe one-shot text-to-speech and speech-to-text",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,9 +28,9 @@
   ],
   "dependencies": {
     "@sinclair/typebox": "^0.34.48",
-    "@alfe.ai/agent-api-client": "0.14.0",
-    "@alfe.ai/config": "0.4.0",
-    "@alfe.ai/openclaw-plugin-kit": "0.1.0"
+    "@alfe.ai/agent-api-client": "0.15.0",
+    "@alfe.ai/config": "0.4.1",
+    "@alfe.ai/openclaw-plugin-kit": "0.2.0"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.0"