@alfe.ai/mcp-tools 0.2.4 → 0.2.6

package/README.md

@@ -1,6 +1,17 @@
 # @alfe.ai/mcp-tools
 
-Shared MCP tool implementations for Alfe's local CLI-bundled MCP server and (later) the Fly-deployed services/mcp. All tools use AgentApiClient against public /agent/... endpoints — never InternalClient.
+Shared MCP tool implementations for Alfe's local CLI-bundled MCP server. All
+Alfe API calls use `AgentApiClient` against public agent endpoints — never
+`InternalClient` or raw authenticated `fetch`.
+
+The package exports registrars for integrations, memory, one-shot voice, and
+outbound SMS. The server chooses which registrars to expose for each runtime
+profile.
+
+Model-controlled file arguments are workspace-relative and realpath-contained.
+Memory and audio inputs are size-bounded; voice output creates a new file and
+never overwrites an existing path. Tool schemas mirror the downstream public
+API's string, enum, and numeric limits.
 
 Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: build, deploy, and run agents with persistent memory, identity, integrations, and channels. See the [documentation](https://docs.alfe.ai) to get started.
 
@@ -10,6 +21,8 @@ Part of [**Alfe**](https://alfe.ai) — the operating system for AI agents: buil
 npm install @alfe.ai/mcp-tools
 ```
 
+See [`DEVELOPING.md`](DEVELOPING.md) for the tool and filesystem contracts.
+
 ## Links
 
 - 🌐 Website: <https://alfe.ai>

package/dist/index.cjs

@@ -1,5 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let zod = require("zod");
+let node_util = require("node:util");
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 //#region src/types.ts
 function ok(data) {
@@ -20,16 +23,34 @@ function err(message) {
 //#endregion
 //#region src/integrations.ts
 const OAUTH_PROVIDERS = [
-	"xero",
+	"atlassian",
+	"ctrader",
+	"discord",
+	"github",
 	"google",
-	"notion",
 	"microsoft",
-	"atlassian",
 	"myob",
-	"github",
-	"discord",
-	"slack"
+	"notion",
+	"salesforce",
+	"shopify",
+	"slack",
+	"x",
+	"xero"
 ];
+function oauthStartUrl(ctx, provider, scopes, shop) {
+	if (!ctx.agentId || ctx.agentId.length > 256 || !ctx.tenantId || ctx.tenantId.length > 256) throw new Error("OAuth context is missing a valid agent or tenant identity.");
+	const url = new URL(ctx.apiUrl);
+	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("OAuth API URL must be an HTTP(S) URL without embedded credentials.");
+	url.hash = "";
+	url.search = "";
+	url.pathname = `${url.pathname.replace(/\/+$/u, "")}/connect/oauth/start`;
+	url.searchParams.set("provider", provider);
+	url.searchParams.set("tenantId", ctx.tenantId);
+	url.searchParams.set("scope", `agent:${ctx.agentId}`);
+	if (scopes) url.searchParams.set("scopes", scopes);
+	if (shop) url.searchParams.set("shop", shop);
+	return url.toString();
+}
 /**
 * Thin-slice subset of the `services/mcp` `integrations` domain — only
 * the two subtools whose underlying calls already hit public
@@ -41,7 +62,7 @@ const OAUTH_PROVIDERS = [
 * - `integrations_browse_registry` — public `GET /integrations/registry`
 *   via `AgentApiClient.getRegistry()`.
 * - `integrations_start_oauth` — generates the public
-*   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+*   universal `GET /connect/oauth/start` URL for the user to open in a browser.
 *   Pure URL builder; no server-side call. Completion is confirmed out of
 *   band (the dashboard, or the hosted MCP server's
 *   `integrations_check_oauth_status`) — the local server intentionally has
@@ -62,24 +83,124 @@ const registerIntegrationsTools = (server, ctx) => {
 		description: "Start an OAuth connection flow for an integration. Returns a URL the user must open in their browser to authorize the connection. After the user authorizes, the connection appears in the Alfe dashboard — this local server does not expose a status-check tool, so confirm completion there.",
 		inputSchema: {
 			provider: zod.z.enum(OAUTH_PROVIDERS).describe("The OAuth provider to connect"),
-			scopes: zod.z.string().optional().describe("Comma-separated scope groups (e.g. 'gmail,drive' for Google)")
+			scopes: zod.z.string().trim().min(1).max(1024).optional().describe("Comma-separated scope groups (e.g. 'gmail,drive' for Google)"),
+			shop: zod.z.string().trim().min(1).max(512).optional().describe("Shopify store handle or myshopify.com domain (required for Shopify only)")
+		}
+	}, ({ provider, scopes, shop }) => {
+		try {
+			if (provider === "shopify" && !shop) return Promise.resolve(err("Shopify OAuth requires the shop handle or myshopify.com domain."));
+			if (provider !== "shopify" && shop) return Promise.resolve(err("The shop argument is only valid for Shopify OAuth."));
+			const url = oauthStartUrl(ctx, provider, scopes, shop);
+			return Promise.resolve(ok({
+				url,
+				provider,
+				message: `Open this URL to connect ${provider}: ${url}`
+			}));
+		} catch (error) {
+			return Promise.resolve(err(error instanceof Error ? error.message : "Failed to generate OAuth URL"));
 		}
-	}, ({ provider, scopes }) => {
-		const params = new URLSearchParams({
-			agentId: ctx.agentId,
-			tenantId: ctx.tenantId
-		});
-		if (scopes) params.set("scopes", scopes);
-		const url = `${ctx.apiUrl}/${provider}/oauth/start?${params.toString()}`;
-		return Promise.resolve(ok({
-			url,
-			provider,
-			message: `Open this URL to connect ${provider}: ${url}`
-		}));
 	});
 };
 //#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());
+}
+/**
+* Read a regular file that resolves inside the current workspace.
+*
+* The lexical check rejects obvious traversal, while `realpath` closes the
+* symlink escape that a simple `resolve(...).startsWith(...)` check leaves
+* open. The descriptor is opened with `O_NOFOLLOW`, then size-checked both
+* before and after the read so a growing file cannot bypass the byte cap.
+*/
+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();
+	}
+}
+/**
+* Write a new file beneath the current workspace without following a parent
+* symlink outside it and without replacing an existing file.
+*/
+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/memory.ts
+const MEMORY_TAGS = [
+	"fact",
+	"decision",
+	"preference",
+	"event",
+	"discovery"
+];
+const MAX_MEMORY_TEXT_CHARACTERS = 1e5;
+const MAX_MEMORY_FILE_BYTES = MAX_MEMORY_TEXT_CHARACTERS * 4;
 /**
 * Memory tools — a runtime-agnostic mirror of the OpenClaw memory-cloud
 * plugin (`@alfe.ai/openclaw-memory-cloud`). All 7 tools (memory_recall,
@@ -104,10 +225,10 @@ const registerMemoryTools = (server, ctx) => {
 	server.registerTool("memory_recall", {
 		description: "Search conversation memory and knowledge graph. Returns structured facts and relevant conversation excerpts.",
 		inputSchema: {
-			query: zod.z.string().describe("What to search for"),
-			limit: zod.z.coerce.number().optional().describe("Maximum results (default 10)"),
-			topic: zod.z.string().optional().describe("Filter by topic"),
-			tag: zod.z.string().optional().describe("Filter by tag (fact/decision/preference/event/discovery)")
+			query: zod.z.string().trim().min(1).max(4e3).describe("What to search for"),
+			limit: zod.z.coerce.number().int().min(1).max(50).optional().describe("Maximum results (default 10)"),
+			topic: zod.z.string().trim().min(1).max(256).optional().describe("Filter by topic"),
+			tag: zod.z.enum(MEMORY_TAGS).optional().describe("Filter by tag (fact/decision/preference/event/discovery)")
 		}
 	}, async (args) => {
 		try {
@@ -123,10 +244,10 @@ const registerMemoryTools = (server, ctx) => {
 	server.registerTool("memory_store", {
 		description: "Explicitly save a piece of information to long-term memory.",
 		inputSchema: {
-			text: zod.z.string().describe("The information to remember"),
-			topic: zod.z.string().optional().describe("Topic category (e.g., person name, project)"),
-			tag: zod.z.string().optional().describe("Memory type: fact, decision, preference, event, discovery"),
-			importance: zod.z.coerce.number().optional().describe("Importance 0-1 (default 0.7)")
+			text: zod.z.string().trim().min(1).max(5e3).describe("The information to remember"),
+			topic: zod.z.string().trim().min(1).max(128).optional().describe("Topic category (e.g., person name, project)"),
+			tag: zod.z.enum(MEMORY_TAGS).optional().describe("Memory type: fact, decision, preference, event, discovery"),
+			importance: zod.z.coerce.number().min(0).max(1).optional().describe("Importance 0-1 (default 0.7)")
 		}
 	}, async (args) => {
 		try {
@@ -146,27 +267,24 @@ const registerMemoryTools = (server, ctx) => {
 	server.registerTool("memory_learn", {
 		description: "Save arbitrary content (a paragraph, a doc, a fact list) into long-term memory. The system auto-classifies and extracts entities. Use this when the user asks you to learn, remember, or study something — or when you read a document worth retaining. Pass the source text directly; do not paraphrase first.",
 		inputSchema: {
-			content: zod.z.string().optional().describe("Inline text to ingest. Provide either content OR path, not both."),
-			path: zod.z.string().optional().describe("Workspace-relative file path to read and ingest. Provide either content OR path, not both."),
-			source: zod.z.string().optional().describe("Optional label describing where the content came from (e.g. doc title, url).")
+			content: zod.z.string().min(1).max(MAX_MEMORY_TEXT_CHARACTERS).optional().describe("Inline text to ingest. Provide either content OR path, not both."),
+			path: zod.z.string().min(1).max(1024).optional().describe("Workspace-relative file path to read and ingest. Provide either content OR path, not both."),
+			source: zod.z.string().min(1).max(512).optional().describe("Optional label describing where the content came from (e.g. doc title, url).")
 		}
 	}, async (args) => {
 		const content = typeof args.content === "string" ? args.content : void 0;
 		const filePath = typeof args.path === "string" ? args.path : void 0;
 		const source = typeof args.source === "string" ? args.source : void 0;
-		if (!content && !filePath) return err("Error: provide either `content` or `path`.");
-		if (content && filePath) return err("Error: provide either `content` or `path`, not both.");
+		if (content === void 0 && filePath === void 0) return err("Error: provide either `content` or `path`.");
+		if (content !== void 0 && filePath !== void 0) return err("Error: provide either `content` or `path`, not both.");
+		if (source !== void 0 && (source.length < 1 || source.length > 512)) return err("Error: source must contain 1–512 characters.");
 		let text;
 		let resolvedSource = source;
 		let sourceType = "inline";
 		if (filePath !== void 0) {
-			const nodePath = await import("node:path");
-			const fs = await import("node:fs/promises");
-			const cwd = process.cwd();
-			const resolved = nodePath.resolve(cwd, filePath);
-			if (!resolved.startsWith(cwd + nodePath.sep) && resolved !== cwd) return err(`Error: path "${filePath}" escapes the workspace.`);
 			try {
-				text = await fs.readFile(resolved, "utf8");
+				const { data } = await readWorkspaceFile(filePath, MAX_MEMORY_FILE_BYTES);
+				text = new node_util.TextDecoder("utf-8", { fatal: true }).decode(data);
 			} catch (readErr) {
 				return err(`Error reading "${filePath}": ${readErr instanceof Error ? readErr.message : String(readErr)}`);
 			}
@@ -174,6 +292,7 @@ const registerMemoryTools = (server, ctx) => {
 			sourceType = "file";
 		} else if (content !== void 0) text = content;
 		else return err("Error: provide either `content` or `path`.");
+		if (text.trim().length === 0 || text.length > MAX_MEMORY_TEXT_CHARACTERS) return err(`Error: memory content must contain 1–${String(MAX_MEMORY_TEXT_CHARACTERS)} characters.`);
 		try {
 			const result = await ctx.client.memoryLearn({
 				text,
@@ -194,7 +313,7 @@ const registerMemoryTools = (server, ctx) => {
 	});
 	server.registerTool("memory_forget", {
 		description: "Search for and delete memories matching a query.",
-		inputSchema: { query: zod.z.string().describe("Search for memories to delete") }
+		inputSchema: { query: zod.z.string().trim().min(1).max(4e3).describe("Search for memories to delete") }
 	}, async (args) => {
 		try {
 			const results = await ctx.client.memorySearch(args.query, { limit: 5 });
@@ -218,7 +337,7 @@ const registerMemoryTools = (server, ctx) => {
 	});
 	server.registerTool("memory_graph", {
 		description: "Look up what you know about a specific entity from the knowledge graph.",
-		inputSchema: { entity: zod.z.string().describe("The entity to look up (person, concept, system)") }
+		inputSchema: { entity: zod.z.string().trim().min(1).max(512).describe("The entity to look up (person, concept, system)") }
 	}, async ({ entity }) => {
 		try {
 			const result = await ctx.client.memoryLookupEntity(entity);
@@ -266,8 +385,26 @@ const registerMemoryTools = (server, ctx) => {
 };
 //#endregion
 //#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;
@@ -288,35 +425,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,
@@ -326,6 +487,9 @@ function parseWav(buf) {
 }
 //#endregion
 //#region src/voice.ts
+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}$/u;
 /**
 * Voice tools — a runtime-agnostic mirror of the one-shot TTS/STT tools in
 * the OpenClaw voice plugin (`@alfe.ai/openclaw-voice`). The channel-only
@@ -344,42 +508,48 @@ function parseWav(buf) {
 */
 const registerVoiceTools = (server, ctx) => {
 	const voiceClient = ctx.voiceClient ?? ctx.client;
-	const resolveWorkspacePath = (p) => (0, node_path.isAbsolute)(p) ? p : (0, node_path.resolve)(process.cwd(), p);
 	server.registerTool("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.",
 		inputSchema: {
-			text: zod.z.string().describe("Text to synthesize (1–5000 characters)."),
-			outputPath: zod.z.string().optional().describe("Where to write the audio file (absolute, or relative to the working directory). Defaults to alfe-tts-<timestamp>.wav in the working directory."),
+			text: zod.z.string().trim().min(1).max(5e3).describe("Text to synthesize (1–5000 characters)."),
+			outputPath: zod.z.string().min(1).max(1024).optional().describe("New workspace-relative audio file to create. Existing files are never overwritten. Defaults to alfe-tts-<timestamp>.wav."),
 			format: zod.z.enum(["wav", "pcm"]).optional().describe("Output container. 'wav' (default) is a playable file; 'pcm' is headerless 24kHz/mono/16-bit raw PCM."),
-			voiceId: zod.z.string().optional().describe("ElevenLabs voice ID. Platform default when omitted."),
+			voiceId: zod.z.string().regex(VOICE_ID_PATTERN).optional().describe("ElevenLabs voice ID. Platform default when omitted."),
 			model: zod.z.enum(["eleven_turbo_v2_5", "eleven_multilingual_v2"]).optional().describe("TTS model. eleven_turbo_v2_5 (lower latency) when omitted.")
 		}
 	}, async (args) => {
 		try {
-			const { writeFile } = await import("node:fs/promises");
 			const format = args.format ?? "wav";
+			const text = args.text.trim();
+			if (text.length < 1 || text.length > 5e3) return err("voice_tts text must contain 1–5000 characters.");
+			if (args.voiceId !== void 0 && !VOICE_ID_PATTERN.test(args.voiceId)) return err("voice_tts voiceId contains unsupported characters.");
+			const outputPath = args.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
+			await resolveWorkspaceOutputPath(outputPath);
 			const result = await voiceClient.tts({
-				text: args.text,
+				text,
 				voiceId: args.voiceId,
 				model: args.model
 			});
+			if (result.audio.length === 0 || result.audio.length > MAX_TTS_RESPONSE_BYTES) return err(`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 = args.outputPath ?? `alfe-tts-${String(Date.now())}.${format}`;
-			const absolutePath = resolveWorkspacePath(outputPath);
-			await writeFile(absolutePath, bytes);
 			return ok({
 				path: outputPath,
-				absolutePath,
+				absolutePath: await writeWorkspaceFileExclusive(outputPath, bytes),
 				format,
 				sampleRate: result.sampleRate,
 				channels: result.channels,
 				bitDepth: result.bitDepth,
 				bytes: bytes.length,
-				characters: args.text.length
+				characters: text.length
 			});
 		} catch (error) {
 			return err(error instanceof Error ? error.message : "voice_tts failed");
@@ -388,13 +558,12 @@ const registerVoiceTools = (server, ctx) => {
 	server.registerTool("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.",
 		inputSchema: {
-			path: zod.z.string().describe("Path to the audio file (absolute, or relative to the working directory). WAV or raw linear16 mono PCM."),
-			sampleRate: zod.z.coerce.number().optional().describe("Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000.")
+			path: zod.z.string().min(1).max(1024).describe("Workspace-relative path to a WAV or raw linear16 mono PCM file (maximum 10 MiB)."),
+			sampleRate: zod.z.coerce.number().int().min(8e3).max(48e3).optional().describe("Sample rate in Hz (8000–48000). Only used for headerless PCM input; ignored for WAV (its header wins). Defaults to 24000.")
 		}
 	}, async (args) => {
 		try {
-			const { readFile } = await import("node:fs/promises");
-			const raw = await readFile(resolveWorkspacePath(args.path));
+			const { data: raw } = await readWorkspaceFile(args.path, MAX_AUDIO_FILE_BYTES);
 			const wav = parseWav(raw);
 			let audio;
 			let sampleRate;
@@ -406,6 +575,8 @@ const registerVoiceTools = (server, ctx) => {
 				audio = raw;
 				sampleRate = args.sampleRate ?? 24e3;
 			}
+			if (!Number.isInteger(sampleRate) || sampleRate < 8e3 || sampleRate > 48e3) return err("voice_stt sampleRate must be an integer between 8000 and 48000 Hz.");
+			if (audio.length === 0 || audio.length % 2 !== 0) return err("voice_stt needs non-empty 16-bit PCM with an even byte length.");
 			return ok(await voiceClient.stt({
 				audio,
 				sampleRate
@@ -431,8 +602,8 @@ const registerMessagingTools = (server, ctx) => {
 	server.registerTool("send_text_message", {
 		description: "Send an SMS text message to a phone number from your assigned phone number. The recipient is any E.164 number (e.g. +14155550123). You send from the single number assigned to you — you cannot choose the sender. Billed per message segment to your tenant credit pool. Fails if you have no active phone number.",
 		inputSchema: {
-			to: zod.z.string().min(1).describe("Recipient phone number in E.164 format (e.g. +14155550123)."),
-			body: zod.z.string().min(1).describe("The text message body to send.")
+			to: zod.z.string().regex(/^\+[1-9]\d{6,14}$/u).describe("Recipient phone number in E.164 format (e.g. +14155550123)."),
+			body: zod.z.string().min(1).max(4400).describe("The text message body to send.")
 		}
 	}, async (args) => {
 		try {

package/dist/index.d.cts

@@ -82,7 +82,7 @@ declare function err(message: string): ToolResult;
  * - `integrations_browse_registry` — public `GET /integrations/registry`
  *   via `AgentApiClient.getRegistry()`.
  * - `integrations_start_oauth` — generates the public
- *   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+ *   universal `GET /connect/oauth/start` URL for the user to open in a browser.
  *   Pure URL builder; no server-side call. Completion is confirmed out of
  *   band (the dashboard, or the hosted MCP server's
  *   `integrations_check_oauth_status`) — the local server intentionally has

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/integrations.ts","../src/memory.ts","../src/voice.ts","../src/messaging.ts"],"mappings":";;;;;;;AAcA;;;;;AAkCA;;;;AAAkE,UAlCjD,WAAA,CAkCiD;EAYjD,MAAA,EA7CP,cA6CiB;EAMX,MAAE,EAAA,MAAA;EAMF,OAAG,EAAA,MAAA;;;;ACxCnB;;;;ACTA;;;;ACDA;;;;ACTA;;;gBJuBgB;;;;;;;;;;;KAYJ,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AA1DtC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;cCxCa,2BAA2B;;;;;;;;ADlBxC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;;;ACxCA;cCTa,qBAAqB;;;;;;;AFTlC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;cGlDa,oBAAoB;;;;;;;AHRjC;;;;;AAkCA;;AAAuC,cInC1B,sBJmC0B,EInCF,eJmCE"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/integrations.ts","../src/memory.ts","../src/voice.ts","../src/messaging.ts"],"mappings":";;;;;;;AAcA;;;;;AAkCA;;;;AAAkE,UAlCjD,WAAA,CAkCiD;EAYjD,MAAA,EA7CP,cA6CiB;EAMX,MAAE,EAAA,MAAA;EAMF,OAAG,EAAA,MAAA;;;;ACXnB;;;;AC/BA;;;;ACAA;;;;ACjBA;;;gBJuBgB;;;;;;;;;;;KAYJ,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AA1DtC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;cCXa,2BAA2B;;;;;;;;AD/CxC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;;;ACXA;cC/Ba,qBAAqB;;;;;;;AFhBlC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;cG1Ca,oBAAoB;;;;;;;AHhBjC;;;;;AAkCA;;AAAuC,cInC1B,sBJmC0B,EInCF,eJmCE"}

package/dist/index.d.ts

@@ -82,7 +82,7 @@ declare function err(message: string): ToolResult;
  * - `integrations_browse_registry` — public `GET /integrations/registry`
  *   via `AgentApiClient.getRegistry()`.
  * - `integrations_start_oauth` — generates the public
- *   `GET /<provider>/oauth/start` URL for the user to open in a browser.
+ *   universal `GET /connect/oauth/start` URL for the user to open in a browser.
  *   Pure URL builder; no server-side call. Completion is confirmed out of
  *   band (the dashboard, or the hosted MCP server's
  *   `integrations_check_oauth_status`) — the local server intentionally has

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/integrations.ts","../src/memory.ts","../src/voice.ts","../src/messaging.ts"],"mappings":";;;;;;;AAcA;;;;;AAkCA;;;;AAAkE,UAlCjD,WAAA,CAkCiD;EAYjD,MAAA,EA7CP,cA6CiB;EAMX,MAAE,EAAA,MAAA;EAMF,OAAG,EAAA,MAAA;;;;ACxCnB;;;;ACTA;;;;ACDA;;;;ACTA;;;gBJuBgB;;;;;;;;;;;KAYJ,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AA1DtC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;cCxCa,2BAA2B;;;;;;;;ADlBxC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;;;ACxCA;cCTa,qBAAqB;;;;;;;AFTlC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;cGlDa,oBAAoB;;;;;;;AHRjC;;;;;AAkCA;;AAAuC,cInC1B,sBJmC0B,EInCF,eJmCE"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/integrations.ts","../src/memory.ts","../src/voice.ts","../src/messaging.ts"],"mappings":";;;;;;;AAcA;;;;;AAkCA;;;;AAAkE,UAlCjD,WAAA,CAkCiD;EAYjD,MAAA,EA7CP,cA6CiB;EAMX,MAAE,EAAA,MAAA;EAMF,OAAG,EAAA,MAAA;;;;ACXnB;;;;AC/BA;;;;ACAA;;;;ACjBA;;;gBJuBgB;;;;;;;;;;;KAYJ,eAAA,YAA2B,gBAAgB;;;;;;;;;;;UAYtC,UAAA;;;;;;;;iBAMD,EAAA,iBAAmB;iBAMnB,GAAA,mBAAsB;;;;;;;AA1DtC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;cCXa,2BAA2B;;;;;;;;AD/CxC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;;;;ACXA;cC/Ba,qBAAqB;;;;;;;AFhBlC;;;;;AAkCA;;;;;AAYA;AAMA;AAMA;cG1Ca,oBAAoB;;;;;;;AHhBjC;;;;;AAkCA;;AAAuC,cInC1B,sBJmC0B,EInCF,eJmCE"}