@vellumai/assistant 0.8.6 → 0.8.7

package/src/tools/host-terminal/host-shell.ts

@@ -37,7 +37,11 @@ import {
 } from "../background-tool-registry.js";
 import { formatShellOutput } from "../shared/shell-output.js";
 import { buildSanitizedEnv } from "../terminal/safe-env.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
 const log = getLogger("host-shell-tool");
 
@@ -91,52 +95,52 @@ function buildHostBashProxyEnv(
   return env;
 }
 
-class HostShellTool implements Tool {
-  name = "host_bash";
-  description =
-    "LAST RESORT — Execute a shell command directly on the host machine. You MUST strongly prefer the regular `bash` tool for all commands. Only use `host_bash` when you are absolutely certain the command MUST run on the host machine and CANNOT run in the workspace (e.g., managing host-level system services, accessing host-only peripherals, or interacting with host paths outside the workspace). If in doubt, use `bash` instead. Approval-gated: each invocation must be explicitly approved. Do not use for commands that require injected credentials or secrets.";
-  category = "host-terminal";
-  executionTarget = "host" as const;
+export const hostShellTool = {
+  name: "host_bash",
+  description:
+    "LAST RESORT — Execute a shell command directly on the host machine. You MUST strongly prefer the regular `bash` tool for all commands. Only use `host_bash` when you are absolutely certain the command MUST run on the host machine and CANNOT run in the workspace (e.g., managing host-level system services, accessing host-only peripherals, or interacting with host paths outside the workspace). If in doubt, use `bash` instead. Approval-gated: each invocation must be explicitly approved. Do not use for commands that require injected credentials or secrets.",
+  category: "host-terminal",
+  executionTarget: "host",
   // host_bash is a weaker-tier escape hatch under CES lockdown. It remains
   // Medium risk by default but persistent approvals are disabled for
   // untrusted sessions (see execute()).
-  defaultRiskLevel = RiskLevel.Medium;
-
-  input_schema = {
-        type: "object",
-        properties: {
-          command: {
-            type: "string",
-            description: "The host shell command to execute.",
-          },
-          activity: {
-            type: "string",
-            description:
-              'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
-          },
-          working_dir: {
-            type: "string",
-            description:
-              "Optional absolute host working directory (defaults to user home)",
-          },
-          timeout_seconds: {
-            type: "number",
-            description:
-              "Optional timeout in seconds. Uses configured default and max limits.",
-          },
-          background: {
-            type: "boolean",
-            description:
-              "Run the command in the background on the host machine. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
-          },
-          target_client_id: {
-            type: "string",
-            description:
-              "ID of the specific client to execute this command on. Required when multiple clients support host_bash; omit when only one client is connected. Obtain IDs from `assistant clients list --capability host_bash`.",
-          },
-        },
-        required: ["command", "activity"],
-      };
+  defaultRiskLevel: RiskLevel.Medium,
+
+  input_schema: {
+    type: "object",
+    properties: {
+      command: {
+        type: "string",
+        description: "The host shell command to execute.",
+      },
+      activity: {
+        type: "string",
+        description:
+          'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
+      },
+      working_dir: {
+        type: "string",
+        description:
+          "Optional absolute host working directory (defaults to user home)",
+      },
+      timeout_seconds: {
+        type: "number",
+        description:
+          "Optional timeout in seconds. Uses configured default and max limits.",
+      },
+      background: {
+        type: "boolean",
+        description:
+          "Run the command in the background on the host machine. The tool returns immediately with a background tool ID. When the process exits, its output is delivered to the conversation as a wake.",
+      },
+      target_client_id: {
+        type: "string",
+        description:
+          "ID of the specific client to execute this command on. Required when multiple clients support host_bash; omit when only one client is connected. Obtain IDs from `assistant clients list --capability host_bash`.",
+      },
+    },
+    required: ["command", "activity"],
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -565,7 +569,5 @@ class HostShellTool implements Tool {
         });
       });
     });
-  }
-}
-
-export const hostShellTool: Tool = new HostShellTool();
+  },
+} satisfies ToolDefinition;

package/src/tools/memory/register.ts

@@ -11,17 +11,21 @@ import {
 } from "../../memory/graph/tools.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 
 // ── remember ────────────────────────────────────────────────────────
 
-class RememberTool implements Tool {
-  name = "remember";
-  description = graphRememberDefinition.description;
-  category = "memory";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
-  input_schema = graphRememberDefinition.input_schema;
+export const rememberTool = {
+  name: "remember",
+  description: graphRememberDefinition.description,
+  category: "memory",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
+  input_schema: graphRememberDefinition.input_schema,
 
   async execute(
     input: Record<string, unknown>,
@@ -39,18 +43,18 @@ class RememberTool implements Tool {
       isError: !result.success,
       ...(typedInput.finish_turn === true ? { yieldToUser: true } : {}),
     };
-  }
-}
+  },
+} satisfies ToolDefinition;
 
 // ── recall ──────────────────────────────────────────────────────────
 
-class RecallTool implements Tool {
-  name = "recall";
-  description = graphRecallDefinition.description;
-  category = "memory";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
-  input_schema = graphRecallDefinition.input_schema;
+export const recallTool = {
+  name: "recall",
+  description: graphRecallDefinition.description,
+  category: "memory",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
+  input_schema: graphRecallDefinition.input_schema,
 
   async execute(
     input: Record<string, unknown>,
@@ -73,10 +77,5 @@ class RecallTool implements Tool {
     });
 
     return { content: result.content, isError: false };
-  }
-}
-
-// ── Exported tool instances ──────────────────────────────────────────
-
-export const rememberTool = new RememberTool();
-export const recallTool = new RecallTool();
+  },
+} satisfies ToolDefinition;

package/src/tools/network/web-fetch.ts

@@ -12,7 +12,11 @@ import { faviconUrlForDomain } from "../../util/favicon.js";
 import { getLogger } from "../../util/logger.js";
 import { safeStringSlice } from "../../util/unicode.js";
 import { registerTool } from "../registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 import { extractDomain } from "./domain-normalize.js";
 import {
   buildHostHeader,
@@ -984,56 +988,55 @@ export async function executeWebFetch(
   }
 }
 
-class WebFetchTool implements Tool {
-  name = "web_fetch";
-  description =
-    "Fetch a webpage and return LLM-friendly extracted text with metadata. Use this after web_search when you need to read a specific result. To find pages on a site without guessing slugs, fetch /sitemap.xml first — it has ground-truth paths and works even when pages are JS-rendered.";
-  category = "network";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
-
-  input_schema = {
-        type: "object",
-        properties: {
-          url: {
-            type: "string",
-            description:
-              "The target webpage URL. If scheme is missing, https:// is assumed.",
-          },
-          max_chars: {
-            type: "number",
-            description: `Maximum characters of content to return (1-${MAX_MAX_CHARS}, default ${DEFAULT_MAX_CHARS})`,
-          },
-          start_index: {
-            type: "number",
-            description:
-              "Character index to start returning content from (default 0). Useful for paging large pages.",
-          },
-          timeout_seconds: {
-            type: "number",
-            description: `Request timeout in seconds (1-${MAX_TIMEOUT_SECONDS}, default ${DEFAULT_TIMEOUT_SECONDS})`,
-          },
-          raw: {
-            type: "boolean",
-            description:
-              "If true, return normalized raw response text instead of extracted plain text for HTML pages.",
-          },
-          allow_private_network: {
-            type: "boolean",
-            description:
-              "If true, allows requests to localhost/private-network hosts. Disabled by default for SSRF safety.",
-          },
-        },
-        required: ["url"],
-      };
+export const webFetchTool = {
+  name: "web_fetch",
+  description:
+    "Fetch a webpage and return LLM-friendly extracted text with metadata. Use this after web_search when you need to read a specific result. To find pages on a site without guessing slugs, fetch /sitemap.xml first — it has ground-truth paths and works even when pages are JS-rendered.",
+  category: "network",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
+
+  input_schema: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description:
+          "The target webpage URL. If scheme is missing, https:// is assumed.",
+      },
+      max_chars: {
+        type: "number",
+        description: `Maximum characters of content to return (1-${MAX_MAX_CHARS}, default ${DEFAULT_MAX_CHARS})`,
+      },
+      start_index: {
+        type: "number",
+        description:
+          "Character index to start returning content from (default 0). Useful for paging large pages.",
+      },
+      timeout_seconds: {
+        type: "number",
+        description: `Request timeout in seconds (1-${MAX_TIMEOUT_SECONDS}, default ${DEFAULT_TIMEOUT_SECONDS})`,
+      },
+      raw: {
+        type: "boolean",
+        description:
+          "If true, return normalized raw response text instead of extracted plain text for HTML pages.",
+      },
+      allow_private_network: {
+        type: "boolean",
+        description:
+          "If true, allows requests to localhost/private-network hosts. Disabled by default for SSRF safety.",
+      },
+    },
+    required: ["url"],
+  },
 
   async execute(
     input: Record<string, unknown>,
     context: ToolContext,
   ): Promise<ToolExecutionResult> {
     return executeWebFetch(input, { signal: context.signal });
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const webFetchTool = new WebFetchTool();
 registerTool(webFetchTool);

package/src/tools/network/web-search.ts

@@ -15,7 +15,11 @@ import {
   sleep,
 } from "../../util/retry.js";
 import { registerTool } from "../registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
+import type {
+  ToolContext,
+  ToolDefinition,
+  ToolExecutionResult,
+} from "../types.js";
 import { extractDomain } from "./domain-normalize.js";
 import type { ManagedSearchProxyResult } from "./managed-search-proxy.js";
 
@@ -769,14 +773,14 @@ const WEB_SEARCH_FALLBACK_ORDER: readonly WebSearchProvider[] = Object.values(
   .sort((a, b) => a.fallbackOrder - b.fallbackOrder)
   .map((adapter) => adapter.id);
 
-class WebSearchTool implements Tool {
-  name = "web_search";
-  description =
-    "Search the web and return results. Useful for looking up current information, documentation, or anything the assistant doesn't know.";
-  category = "network";
-  executionTarget = "sandbox" as const;
-  defaultRiskLevel = RiskLevel.Low;
-  input_schema = {
+export const webSearchTool = {
+  name: "web_search",
+  description:
+    "Search the web and return results. Useful for looking up current information, documentation, or anything the assistant doesn't know.",
+  category: "network",
+  executionTarget: "sandbox",
+  defaultRiskLevel: RiskLevel.Low,
+  input_schema: {
     type: "object",
     properties: {
       query: {
@@ -800,7 +804,7 @@ class WebSearchTool implements Tool {
       },
     },
     required: ["query"],
-  };
+  },
 
   async execute(
     input: Record<string, unknown>,
@@ -902,8 +906,7 @@ class WebSearchTool implements Tool {
         `Web search failed: ${msg}`,
       );
     }
-  }
-}
+  },
+} satisfies ToolDefinition;
 
-export const webSearchTool = new WebSearchTool();
 registerTool(webSearchTool);

package/src/tools/registry.ts

@@ -1,4 +1,3 @@
-import type { ToolDefinition } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
 import { coreAppProxyTools } from "./apps/definitions.js";
 import { registerAppTools } from "./apps/registry.js";
@@ -9,7 +8,8 @@ import { hostFileWriteTool } from "./host-filesystem/write.js";
 import { hostShellTool } from "./host-terminal/host-shell.js";
 import { toProviderSafeToolName } from "./provider-tool-name.js";
 import { registerSystemTools } from "./system/register.js";
-import type { LoadedTool, OwnerInfo, Tool } from "./types.js";
+import { finalizeTool } from "./tool-defaults.js";
+import type { OwnerInfo, Tool, ToolDefinition } from "./types.js";
 import { allUiSurfaceTools } from "./ui-surface/definitions.js";
 import { registerUiSurfaceTools } from "./ui-surface/registry.js";
 
@@ -130,14 +130,34 @@ function withProviderSafeToolName(tool: Tool): Tool {
   };
 }
 
-export function registerTool(tool: Tool): void {
-  const existing = tools.get(tool.name);
+/**
+ * Memoize `finalizeTool(definition, name)` by the definition reference so
+ * idempotent re-registration (test reset helpers, module re-imports) stays a
+ * silent no-op — the same `ToolDefinition` always finalizes to the same `Tool`
+ * instance, and the existing `existing === tool` short-circuit below keeps
+ * working.
+ */
+const finalizedByDefinition = new WeakMap<ToolDefinition, Tool>();
+
+export function registerTool(definition: ToolDefinition): void {
+  const name = definition.name;
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error(
+      "registerTool: tool.name is required — set it on the literal or finalize through `finalizeTool(def, name)` first",
+    );
+  }
+  let tool = finalizedByDefinition.get(definition);
+  if (!tool) {
+    tool = finalizeTool(definition, name);
+    finalizedByDefinition.set(definition, tool);
+  }
+  const existing = tools.get(name);
   if (existing) {
-    if (existing === tool) return; // same object, skip
-    log.warn({ name: tool.name }, "Tool already registered, overwriting");
+    if (existing === tool) return; // same definition re-registered, skip
+    log.warn({ name }, "Tool already registered, overwriting");
   }
-  tools.set(tool.name, tool);
-  log.info({ name: tool.name, category: tool.category }, "Tool registered");
+  tools.set(name, tool);
+  log.info({ name, category: tool.category }, "Tool registered");
 }
 
 export function getTool(name: string): Tool | undefined {
@@ -235,7 +255,7 @@ export function registerSkillTools(skillId: string, newTools: Tool[]): Tool[] {
  */
 export function registerPluginTools(
   pluginName: string,
-  newTools: LoadedTool[],
+  newTools: Tool[],
 ): Tool[] {
   const stamped: Tool[] = newTools.map((pluginTool) => {
     const tool: Tool = {
@@ -423,7 +443,7 @@ export function unregisterAllMcpTools(): void {
  * Used by the session resolver to dynamically pick up MCP tools that
  * were registered after session creation (e.g. via `vellum mcp reload`).
  */
-export function getMcpToolDefinitions(): ToolDefinition[] {
+export function getMcpToolDefinitions(): Tool[] {
   return Array.from(tools.values()).filter(
     (t) => ownersByName.get(t.name)?.kind === "mcp",
   );
@@ -445,7 +465,7 @@ export function getSkillRefCount(skillId: string): number {
   return skillRefCount.get(skillId) ?? 0;
 }
 
-export function getAllToolDefinitions(): ToolDefinition[] {
+export function getAllToolDefinitions(): Tool[] {
   // Exclude skill-origin tools - they are managed by the session-level
   // skill projection system (projectSkillTools) and must not leak into
   // the base tool list, which is shared across sessions via the global
@@ -522,14 +542,17 @@ export async function initializeTools(): Promise<void> {
   // registered external skill tool).  This handles ESM cache hits where
   // eager-module tools are already in the registry before init ran.
   if (!coreToolsSnapshot) {
+    // Core tool literals always set `name` (verified by `registerTool` —
+    // it throws on missing name). The `!` assertions reflect that
+    // invariant at the iteration sites.
     const manifestToolNames = new Set<string>([
       ...eagerModuleToolNames,
-      ...explicitTools.map((t: Tool) => t.name),
+      ...explicitTools.map((t) => t.name!),
       ...extEntries.map(({ tool }) => tool.name),
-      ...hostTools.map((t: Tool) => t.name),
-      ...cesTools.map((t: Tool) => t.name),
-      ...allUiSurfaceTools.map((t: Tool) => t.name),
-      ...coreAppProxyTools.map((t: Tool) => t.name),
+      ...hostTools.map((t) => t.name!),
+      ...cesTools.map((t) => t.name!),
+      ...allUiSurfaceTools.map((t) => t.name!),
+      ...coreAppProxyTools.map((t) => t.name!),
     ]);
 
     coreToolsSnapshot = new Map<string, Tool>();

package/src/tools/schedule/create.ts

@@ -1,6 +1,7 @@
 import { formatIntegrationSummary } from "../../schedule/integration-status.js";
 import { validateRruleSetLines } from "../../schedule/recurrence-engine.js";
 import { normalizeScheduleSyntax } from "../../schedule/recurrence-types.js";
+import { validateScriptTimeoutMs } from "../../schedule/run-script.js";
 import type {
   RoutingIntent,
   ScheduleMode,
@@ -46,6 +47,14 @@ export async function executeScheduleCreate(
   const reuseConversation = input.reuse_conversation as boolean | undefined;
   const maxRetries = input.max_retries as number | undefined;
   const retryBackoffMs = input.retry_backoff_ms as number | undefined;
+  const timeoutMs = input.timeout_ms as number | undefined;
+
+  if (timeoutMs !== undefined) {
+    const timeoutError = validateScriptTimeoutMs(timeoutMs);
+    if (timeoutError) {
+      return { content: `Error: ${timeoutError}`, isError: true };
+    }
+  }
 
   if (!name || typeof name !== "string") {
     return {
@@ -134,6 +143,7 @@ export async function executeScheduleCreate(
         reuseConversation,
         maxRetries,
         retryBackoffMs,
+        timeoutMs,
       });
 
       const fireDate = formatLocalDate(job.nextRunAt);
@@ -214,6 +224,7 @@ export async function executeScheduleCreate(
       reuseConversation,
       maxRetries,
       retryBackoffMs,
+      timeoutMs,
     });
 
     const scheduleDescription =

package/src/tools/schedule/update.ts

@@ -4,6 +4,7 @@ import {
   normalizeScheduleSyntax,
   type ScheduleSyntax,
 } from "../../schedule/recurrence-types.js";
+import { validateScriptTimeoutMs } from "../../schedule/run-script.js";
 import type {
   RoutingIntent,
   ScheduleMode,
@@ -116,6 +117,20 @@ export async function executeScheduleUpdate(
     updates.retryBackoffMs = input.retry_backoff_ms;
   }
 
+  // Script execution timeout override (null clears it, reverting to default)
+  if (input.timeout_ms !== undefined) {
+    if (input.timeout_ms === null) {
+      updates.timeoutMs = null;
+    } else {
+      const timeoutMs = input.timeout_ms as number;
+      const timeoutError = validateScriptTimeoutMs(timeoutMs);
+      if (timeoutError) {
+        return { content: `Error: ${timeoutError}`, isError: true };
+      }
+      updates.timeoutMs = timeoutMs;
+    }
+  }
+
   // Auto-detect syntax when expression changes without explicit syntax
   if (input.expression !== undefined || input.syntax !== undefined) {
     const resolved = normalizeScheduleSyntax({
@@ -183,6 +198,7 @@ export async function executeScheduleUpdate(
         reuseConversation?: boolean;
         maxRetries?: number;
         retryBackoffMs?: number;
+        timeoutMs?: number | null;
       },
     );
 

package/src/tools/shared/filesystem/audio-read.ts

@@ -0,0 +1,122 @@
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+
+import { GEMINI_MAX_INLINE_AUDIO_BYTES } from "../../../providers/gemini/inline-media.js";
+import type { FileContent } from "../../../providers/types.js";
+import type { ToolExecutionResult } from "../../types.js";
+
+/**
+ * Extension → MIME map for audio files the agent can read. Kept identical to
+ * the canonical upload mapping (`migrations/191-backfill-audio-attachment-mime-types`)
+ * so a `.mp3` read produces `audio/mpeg` — the same input the attachment path
+ * feeds `normalizeGeminiAudioMime` (which maps it to Gemini's `audio/mp3`).
+ */
+const EXTENSION_MIME: Record<string, string> = {
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".ogg": "audio/ogg",
+  ".flac": "audio/flac",
+  ".aac": "audio/aac",
+  ".m4a": "audio/x-m4a",
+  ".opus": "audio/opus",
+};
+
+export const AUDIO_EXTENSIONS = new Set(Object.keys(EXTENSION_MIME));
+
+// Audio is sent to Gemini inline; its inline-request ceiling is the binding
+// limit and the only consumer that uses the bytes. Cap the read there rather
+// than embedding a payload that would just be dropped.
+const MAX_AUDIO_BYTES = GEMINI_MAX_INLINE_AUDIO_BYTES;
+const MAX_AUDIO_MB = Math.round(MAX_AUDIO_BYTES / (1024 * 1024));
+
+function buildAudioToolResult(
+  buffer: Buffer,
+  sourceLabel: string,
+  mimeType: string,
+): ToolExecutionResult {
+  if (buffer.length > MAX_AUDIO_BYTES) {
+    const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
+    return {
+      content: `Error: audio too large (${sizeMB} MB). Maximum is ${MAX_AUDIO_MB} MB (the inline-audio limit). Ask for a shorter clip.`,
+      isError: true,
+    };
+  }
+
+  const fileBlock: FileContent = {
+    type: "file",
+    source: {
+      type: "base64",
+      media_type: mimeType,
+      data: buffer.toString("base64"),
+      filename: basename(sourceLabel),
+    },
+  };
+
+  return {
+    content: `Audio loaded: ${sourceLabel} (${buffer.length} bytes, ${mimeType})`,
+    isError: false,
+    contentBlocks: [fileBlock],
+  };
+}
+
+/**
+ * Read an audio file from disk and return a ToolExecutionResult carrying a
+ * base64 `file` content block so an audio-capable model (Gemini) can hear it.
+ * No transcoding — audio can't be cheaply optimized like images.
+ *
+ * The caller is responsible for path resolution and sandbox enforcement —
+ * `resolvedPath` must be an already-validated absolute path.
+ */
+export function readAudioFile(resolvedPath: string): ToolExecutionResult {
+  const mimeType = EXTENSION_MIME[extname(resolvedPath).toLowerCase()];
+  if (!mimeType) {
+    // Defensive: callers gate on AUDIO_EXTENSIONS, so this is unreachable.
+    return {
+      content: `Error: unsupported audio file: ${resolvedPath}`,
+      isError: true,
+    };
+  }
+
+  let stat;
+  try {
+    stat = statSync(resolvedPath);
+  } catch {
+    return { content: `Error: file not found: ${resolvedPath}`, isError: true };
+  }
+  if (!stat.isFile()) {
+    return { content: `Error: ${resolvedPath} is not a file`, isError: true };
+  }
+  if (stat.size > MAX_AUDIO_BYTES) {
+    const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+    return {
+      content: `Error: audio too large (${sizeMB} MB). Maximum is ${MAX_AUDIO_MB} MB (the inline-audio limit). Ask for a shorter clip.`,
+      isError: true,
+    };
+  }
+
+  let buffer: Buffer;
+  try {
+    buffer = readFileSync(resolvedPath) as Buffer;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error reading file: ${msg}`, isError: true };
+  }
+
+  return buildAudioToolResult(buffer, resolvedPath, mimeType);
+}
+
+/**
+ * Build an audio ToolExecutionResult from already-read base64 bytes. Used by
+ * the host-file proxy when a remote client streams audio back over the wire.
+ */
+export function readAudioBase64(
+  base64Data: string,
+  sourceLabel: string,
+  mimeType: string,
+): ToolExecutionResult {
+  return buildAudioToolResult(
+    Buffer.from(base64Data, "base64"),
+    sourceLabel,
+    mimeType,
+  );
+}