@dexto/tools-filesystem 1.6.21 → 1.6.22

package/dist/filesystem-service.cjs

@@ -38,6 +38,7 @@ var import_safe_regex = __toESM(require("safe-regex"), 1);
 var import_core = require("@dexto/core");
 var import_path_validator = require("./path-validator.js");
 var import_errors = require("./errors.js");
+var import_mime_utils = require("./mime-utils.js");
 const DEFAULT_ENCODING = "utf-8";
 const DEFAULT_MAX_RESULTS = 1e3;
 const DEFAULT_MAX_SEARCH_RESULTS = 100;
@@ -195,7 +196,17 @@ class FileSystemService {
     }
     try {
       const encoding = options.encoding || DEFAULT_ENCODING;
-      const content = await fs.readFile(normalizedPath, encoding);
+      const rawContent = await fs.readFile(normalizedPath);
+      const mimeType = (0, import_mime_utils.detectMimeType)(normalizedPath, rawContent);
+      const binaryLike = (0, import_mime_utils.isLikelyBinary)(rawContent);
+      const canReadAsText = !binaryLike && ((0, import_mime_utils.isTextMimeType)(mimeType) || mimeType === "image/svg+xml");
+      if (!canReadAsText) {
+        throw import_errors.FileSystemError.readFailed(
+          normalizedPath,
+          `File is binary (${mimeType}). Use read_media_file instead.`
+        );
+      }
+      const content = rawContent.toString(encoding);
       const lines = content.split("\n");
       const limit = options.limit;
       const offset1 = options.offset;
@@ -214,6 +225,7 @@ class FileSystemService {
         content: returnedContent,
         lines: selectedLines.length,
         encoding,
+        mimeType,
         truncated,
         size: Buffer.byteLength(returnedContent, encoding)
       };
@@ -235,6 +247,55 @@ class FileSystemService {
     const normalizedPath = await this.validateReadPath(filePath, "execute");
     return await this.readNormalizedFile(normalizedPath, options);
   }
+  /**
+   * Read a media or binary file and return base64-encoded data with MIME metadata.
+   */
+  async readMediaFile(filePath) {
+    await this.ensureInitialized();
+    const normalizedPath = await this.validateReadPath(filePath, "execute");
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isFile()) {
+        throw import_errors.FileSystemError.invalidPath(normalizedPath, "Path is not a file");
+      }
+      if (stats.size > this.config.maxFileSize) {
+        throw import_errors.FileSystemError.fileTooLarge(
+          normalizedPath,
+          stats.size,
+          this.config.maxFileSize
+        );
+      }
+      const rawContent = await fs.readFile(normalizedPath);
+      const mimeType = (0, import_mime_utils.detectMimeType)(normalizedPath, rawContent);
+      if ((0, import_mime_utils.isTextMimeType)(mimeType) && !(0, import_mime_utils.isLikelyBinary)(rawContent)) {
+        throw import_errors.FileSystemError.readFailed(
+          normalizedPath,
+          `File is text (${mimeType}). Use read_file instead.`
+        );
+      }
+      return {
+        data: rawContent.toString("base64"),
+        mimeType,
+        filename: path.basename(normalizedPath),
+        kind: (0, import_mime_utils.getMediaFileKind)(mimeType),
+        size: stats.size
+      };
+    } catch (error) {
+      if (error instanceof import_core.DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw import_errors.FileSystemError.fileNotFound(normalizedPath);
+      }
+      if (error.code === "EACCES") {
+        throw import_errors.FileSystemError.permissionDenied(normalizedPath, "read");
+      }
+      throw import_errors.FileSystemError.readFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   /**
    * Preview-only file read that bypasses config-allowed roots.
    *

package/dist/filesystem-service.d.ts

@@ -4,7 +4,7 @@
  * Secure file system operations for Dexto internal tools
  */
 import { Logger } from '@dexto/core';
-import { FileSystemConfig, FileContent, ReadFileOptions, GlobOptions, GlobResult, GrepOptions, SearchResult, WriteFileOptions, WriteResult, EditFileOptions, EditResult, EditOperation, ListDirectoryOptions, ListDirectoryResult, CreateDirectoryOptions, CreateDirectoryResult, DeletePathOptions, DeletePathResult, RenamePathResult } from './types.js';
+import { FileSystemConfig, FileContent, MediaFileContent, ReadFileOptions, GlobOptions, GlobResult, GrepOptions, SearchResult, WriteFileOptions, WriteResult, EditFileOptions, EditResult, EditOperation, ListDirectoryOptions, ListDirectoryResult, CreateDirectoryOptions, CreateDirectoryResult, DeletePathOptions, DeletePathResult, RenamePathResult } from './types.js';
 /**
  * FileSystemService - Handles all file system operations with security checks
  *
@@ -80,6 +80,10 @@ export declare class FileSystemService {
      * Read a file with validation and size limits
      */
     readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
+    /**
+     * Read a media or binary file and return base64-encoded data with MIME metadata.
+     */
+    readMediaFile(filePath: string): Promise<MediaFileContent>;
     /**
      * Preview-only file read that bypasses config-allowed roots.
      *

package/dist/filesystem-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem-service.d.ts","sourceRoot":"","sources":["../src/filesystem-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"filesystem-service.d.ts","sourceRoot":"","sources":["../src/filesystem-service.ts"],"names":[],"mappings":"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"}

package/dist/filesystem-service.js

@@ -5,6 +5,7 @@ import safeRegex from "safe-regex";
 import { DextoRuntimeError, getDextoPath, DextoLogComponent } from "@dexto/core";
 import { PathValidator } from "./path-validator.js";
 import { FileSystemError } from "./errors.js";
+import { detectMimeType, getMediaFileKind, isLikelyBinary, isTextMimeType } from "./mime-utils.js";
 const DEFAULT_ENCODING = "utf-8";
 const DEFAULT_MAX_RESULTS = 1e3;
 const DEFAULT_MAX_SEARCH_RESULTS = 100;
@@ -162,7 +163,17 @@ class FileSystemService {
     }
     try {
       const encoding = options.encoding || DEFAULT_ENCODING;
-      const content = await fs.readFile(normalizedPath, encoding);
+      const rawContent = await fs.readFile(normalizedPath);
+      const mimeType = detectMimeType(normalizedPath, rawContent);
+      const binaryLike = isLikelyBinary(rawContent);
+      const canReadAsText = !binaryLike && (isTextMimeType(mimeType) || mimeType === "image/svg+xml");
+      if (!canReadAsText) {
+        throw FileSystemError.readFailed(
+          normalizedPath,
+          `File is binary (${mimeType}). Use read_media_file instead.`
+        );
+      }
+      const content = rawContent.toString(encoding);
       const lines = content.split("\n");
       const limit = options.limit;
       const offset1 = options.offset;
@@ -181,6 +192,7 @@ class FileSystemService {
         content: returnedContent,
         lines: selectedLines.length,
         encoding,
+        mimeType,
         truncated,
         size: Buffer.byteLength(returnedContent, encoding)
       };
@@ -202,6 +214,55 @@ class FileSystemService {
     const normalizedPath = await this.validateReadPath(filePath, "execute");
     return await this.readNormalizedFile(normalizedPath, options);
   }
+  /**
+   * Read a media or binary file and return base64-encoded data with MIME metadata.
+   */
+  async readMediaFile(filePath) {
+    await this.ensureInitialized();
+    const normalizedPath = await this.validateReadPath(filePath, "execute");
+    try {
+      const stats = await fs.stat(normalizedPath);
+      if (!stats.isFile()) {
+        throw FileSystemError.invalidPath(normalizedPath, "Path is not a file");
+      }
+      if (stats.size > this.config.maxFileSize) {
+        throw FileSystemError.fileTooLarge(
+          normalizedPath,
+          stats.size,
+          this.config.maxFileSize
+        );
+      }
+      const rawContent = await fs.readFile(normalizedPath);
+      const mimeType = detectMimeType(normalizedPath, rawContent);
+      if (isTextMimeType(mimeType) && !isLikelyBinary(rawContent)) {
+        throw FileSystemError.readFailed(
+          normalizedPath,
+          `File is text (${mimeType}). Use read_file instead.`
+        );
+      }
+      return {
+        data: rawContent.toString("base64"),
+        mimeType,
+        filename: path.basename(normalizedPath),
+        kind: getMediaFileKind(mimeType),
+        size: stats.size
+      };
+    } catch (error) {
+      if (error instanceof DextoRuntimeError && error.scope === "filesystem") {
+        throw error;
+      }
+      if (error.code === "ENOENT") {
+        throw FileSystemError.fileNotFound(normalizedPath);
+      }
+      if (error.code === "EACCES") {
+        throw FileSystemError.permissionDenied(normalizedPath, "read");
+      }
+      throw FileSystemError.readFailed(
+        normalizedPath,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
   /**
    * Preview-only file read that bypasses config-allowed roots.
    *

package/dist/filesystem-service.test.cjs

@@ -26,13 +26,23 @@ var path = __toESM(require("node:path"), 1);
 var fs = __toESM(require("node:fs/promises"), 1);
 var os = __toESM(require("node:os"), 1);
 var import_filesystem_service = require("./filesystem-service.js");
-const createMockLogger = () => ({
-  debug: import_vitest.vi.fn(),
-  info: import_vitest.vi.fn(),
-  warn: import_vitest.vi.fn(),
-  error: import_vitest.vi.fn(),
-  createChild: import_vitest.vi.fn().mockReturnThis()
-});
+const createMockLogger = () => {
+  const logger = {
+    debug: import_vitest.vi.fn(),
+    silly: import_vitest.vi.fn(),
+    info: import_vitest.vi.fn(),
+    warn: import_vitest.vi.fn(),
+    error: import_vitest.vi.fn(),
+    trackException: import_vitest.vi.fn(),
+    createChild: import_vitest.vi.fn(() => logger),
+    createFileOnlyChild: import_vitest.vi.fn(() => logger),
+    setLevel: import_vitest.vi.fn(),
+    getLevel: import_vitest.vi.fn(() => "debug"),
+    getLogFilePath: import_vitest.vi.fn(() => null),
+    destroy: import_vitest.vi.fn(async () => void 0)
+  };
+  return logger;
+};
 (0, import_vitest.describe)("FileSystemService", () => {
   let mockLogger;
   let tempDir;
@@ -50,6 +60,112 @@ const createMockLogger = () => ({
     } catch {
     }
   });
+  (0, import_vitest.describe)("Read Modes", () => {
+    (0, import_vitest.it)("returns MIME metadata for text reads", async () => {
+      const fileSystemService = new import_filesystem_service.FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "notes.md");
+      await fs.writeFile(testFile, "# hello\nworld");
+      const result = await fileSystemService.readFile(testFile);
+      (0, import_vitest.expect)(result.content).toBe("# hello\nworld");
+      (0, import_vitest.expect)(result.mimeType).toBe("text/markdown");
+    });
+    (0, import_vitest.it)("rejects binary files from readFile and points callers to readMediaFile", async () => {
+      const fileSystemService = new import_filesystem_service.FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "image.png");
+      await fs.writeFile(testFile, Buffer.from([137, 80, 78, 71, 0, 1]));
+      await (0, import_vitest.expect)(fileSystemService.readFile(testFile)).rejects.toThrow(
+        /Use read_media_file instead/
+      );
+    });
+    (0, import_vitest.it)("rejects binary-like content even when the extension looks textual", async () => {
+      const fileSystemService = new import_filesystem_service.FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "data.json");
+      await fs.writeFile(testFile, Buffer.from([123, 0, 34, 120, 34, 125]));
+      await (0, import_vitest.expect)(fileSystemService.readFile(testFile)).rejects.toThrow(
+        /Use read_media_file instead/
+      );
+    });
+    (0, import_vitest.it)("reads media files as base64 with MIME-aware kind metadata", async () => {
+      const fileSystemService = new import_filesystem_service.FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "clip.mp4");
+      const buffer = Buffer.from([0, 0, 0, 24, 102, 116, 121, 112]);
+      await fs.writeFile(testFile, buffer);
+      const result = await fileSystemService.readMediaFile(testFile);
+      (0, import_vitest.expect)(result.data).toBe(buffer.toString("base64"));
+      (0, import_vitest.expect)(result.mimeType).toBe("video/mp4");
+      (0, import_vitest.expect)(result.kind).toBe("video");
+      (0, import_vitest.expect)(result.filename).toBe("clip.mp4");
+      (0, import_vitest.expect)(result.size).toBe(buffer.length);
+    });
+    (0, import_vitest.it)("rejects text files from readMediaFile and points callers to readFile", async () => {
+      const fileSystemService = new import_filesystem_service.FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "plain.txt");
+      await fs.writeFile(testFile, "hello world");
+      await (0, import_vitest.expect)(fileSystemService.readMediaFile(testFile)).rejects.toThrow(
+        /Use read_file instead/
+      );
+    });
+  });
   (0, import_vitest.describe)("Backup Behavior", () => {
     (0, import_vitest.describe)("writeFile", () => {
       (0, import_vitest.it)("should NOT create backup when enableBackups is false (default)", async () => {

package/dist/filesystem-service.test.js

@@ -3,13 +3,23 @@ import * as path from "node:path";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import { FileSystemService } from "./filesystem-service.js";
-const createMockLogger = () => ({
-  debug: vi.fn(),
-  info: vi.fn(),
-  warn: vi.fn(),
-  error: vi.fn(),
-  createChild: vi.fn().mockReturnThis()
-});
+const createMockLogger = () => {
+  const logger = {
+    debug: vi.fn(),
+    silly: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    trackException: vi.fn(),
+    createChild: vi.fn(() => logger),
+    createFileOnlyChild: vi.fn(() => logger),
+    setLevel: vi.fn(),
+    getLevel: vi.fn(() => "debug"),
+    getLogFilePath: vi.fn(() => null),
+    destroy: vi.fn(async () => void 0)
+  };
+  return logger;
+};
 describe("FileSystemService", () => {
   let mockLogger;
   let tempDir;
@@ -27,6 +37,112 @@ describe("FileSystemService", () => {
     } catch {
     }
   });
+  describe("Read Modes", () => {
+    it("returns MIME metadata for text reads", async () => {
+      const fileSystemService = new FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "notes.md");
+      await fs.writeFile(testFile, "# hello\nworld");
+      const result = await fileSystemService.readFile(testFile);
+      expect(result.content).toBe("# hello\nworld");
+      expect(result.mimeType).toBe("text/markdown");
+    });
+    it("rejects binary files from readFile and points callers to readMediaFile", async () => {
+      const fileSystemService = new FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "image.png");
+      await fs.writeFile(testFile, Buffer.from([137, 80, 78, 71, 0, 1]));
+      await expect(fileSystemService.readFile(testFile)).rejects.toThrow(
+        /Use read_media_file instead/
+      );
+    });
+    it("rejects binary-like content even when the extension looks textual", async () => {
+      const fileSystemService = new FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "data.json");
+      await fs.writeFile(testFile, Buffer.from([123, 0, 34, 120, 34, 125]));
+      await expect(fileSystemService.readFile(testFile)).rejects.toThrow(
+        /Use read_media_file instead/
+      );
+    });
+    it("reads media files as base64 with MIME-aware kind metadata", async () => {
+      const fileSystemService = new FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "clip.mp4");
+      const buffer = Buffer.from([0, 0, 0, 24, 102, 116, 121, 112]);
+      await fs.writeFile(testFile, buffer);
+      const result = await fileSystemService.readMediaFile(testFile);
+      expect(result.data).toBe(buffer.toString("base64"));
+      expect(result.mimeType).toBe("video/mp4");
+      expect(result.kind).toBe("video");
+      expect(result.filename).toBe("clip.mp4");
+      expect(result.size).toBe(buffer.length);
+    });
+    it("rejects text files from readMediaFile and points callers to readFile", async () => {
+      const fileSystemService = new FileSystemService(
+        {
+          allowedPaths: [tempDir],
+          blockedPaths: [],
+          blockedExtensions: [],
+          maxFileSize: 10 * 1024 * 1024,
+          workingDirectory: tempDir,
+          enableBackups: false,
+          backupRetentionDays: 7
+        },
+        mockLogger
+      );
+      await fileSystemService.initialize();
+      const testFile = path.join(tempDir, "plain.txt");
+      await fs.writeFile(testFile, "hello world");
+      await expect(fileSystemService.readMediaFile(testFile)).rejects.toThrow(
+        /Use read_file instead/
+      );
+    });
+  });
   describe("Backup Behavior", () => {
     describe("writeFile", () => {
       it("should NOT create backup when enableBackups is false (default)", async () => {

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   createGlobFilesTool: () => import_glob_files_tool.createGlobFilesTool,
   createGrepContentTool: () => import_grep_content_tool.createGrepContentTool,
   createReadFileTool: () => import_read_file_tool.createReadFileTool,
+  createReadMediaFileTool: () => import_read_media_file_tool.createReadMediaFileTool,
   createWriteFileTool: () => import_write_file_tool.createWriteFileTool,
   fileSystemToolsFactory: () => import_tool_factory.fileSystemToolsFactory
 });
@@ -38,6 +39,7 @@ var import_path_validator = require("./path-validator.js");
 var import_errors = require("./errors.js");
 var import_error_codes = require("./error-codes.js");
 var import_read_file_tool = require("./read-file-tool.js");
+var import_read_media_file_tool = require("./read-media-file-tool.js");
 var import_write_file_tool = require("./write-file-tool.js");
 var import_edit_file_tool = require("./edit-file-tool.js");
 var import_glob_files_tool = require("./glob-files-tool.js");
@@ -53,6 +55,7 @@ var import_grep_content_tool = require("./grep-content-tool.js");
   createGlobFilesTool,
   createGrepContentTool,
   createReadFileTool,
+  createReadMediaFileTool,
   createWriteFileTool,
   fileSystemToolsFactory
 });

package/dist/index.d.cts

@@ -32,7 +32,7 @@ declare const FileSystemToolsConfigSchema: z.ZodObject<{
     enableBackups: z.ZodDefault<z.ZodBoolean>;
     backupPath: z.ZodOptional<z.ZodString>;
     backupRetentionDays: z.ZodDefault<z.ZodNumber>;
-    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["read_file", "write_file", "edit_file", "glob_files", "grep_content"]>, "many">>;
+    enabledTools: z.ZodOptional<z.ZodArray<z.ZodEnum<["read_file", "read_media_file", "write_file", "edit_file", "glob_files", "grep_content"]>, "many">>;
 }, "strict", z.ZodTypeAny, {
     allowedPaths: string[];
     blockedExtensions: string[];
@@ -43,7 +43,7 @@ declare const FileSystemToolsConfigSchema: z.ZodObject<{
     type: "filesystem-tools";
     backupPath?: string | undefined;
     workingDirectory?: string | undefined;
-    enabledTools?: ("read_file" | "write_file" | "edit_file" | "glob_files" | "grep_content")[] | undefined;
+    enabledTools?: ("read_file" | "read_media_file" | "write_file" | "edit_file" | "glob_files" | "grep_content")[] | undefined;
 }, {
     type: "filesystem-tools";
     allowedPaths?: string[] | undefined;
@@ -54,7 +54,7 @@ declare const FileSystemToolsConfigSchema: z.ZodObject<{
     enableBackups?: boolean | undefined;
     backupRetentionDays?: number | undefined;
     workingDirectory?: string | undefined;
-    enabledTools?: ("read_file" | "write_file" | "edit_file" | "glob_files" | "grep_content")[] | undefined;
+    enabledTools?: ("read_file" | "read_media_file" | "write_file" | "edit_file" | "glob_files" | "grep_content")[] | undefined;
 }>;
 type FileSystemToolsConfig = z.output<typeof FileSystemToolsConfigSchema>;
 
@@ -78,6 +78,16 @@ interface FileContent {
     truncated: boolean;
     size: number;
 }
+/**
+ * Media or binary file content with metadata.
+ */
+interface MediaFileContent {
+    data: string;
+    mimeType: string;
+    filename: string;
+    kind: 'image' | 'audio' | 'video' | 'file';
+    size: number;
+}
 /**
  * Options for reading files
  */
@@ -383,6 +393,10 @@ declare class FileSystemService {
      * Read a file with validation and size limits
      */
     readFile(filePath: string, options?: ReadFileOptions): Promise<FileContent>;
+    /**
+     * Read a media or binary file and return base64-encoded data with MIME metadata.
+     */
+    readMediaFile(filePath: string): Promise<MediaFileContent>;
     /**
      * Preview-only file read that bypasses config-allowed roots.
      *
@@ -738,6 +752,21 @@ declare const ReadFileInputSchema: z.ZodObject<{
  */
 declare function createReadFileTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof ReadFileInputSchema>;
 
+/**
+ * Read Media File Tool
+ *
+ * Internal tool for reading media or binary files as base64 with MIME metadata.
+ */
+
+declare const ReadMediaFileInputSchema: z.ZodObject<{
+    file_path: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    file_path: string;
+}, {
+    file_path: string;
+}>;
+declare function createReadMediaFileTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof ReadMediaFileInputSchema>;
+
 /**
  * Write File Tool
  *
@@ -849,4 +878,4 @@ declare const GrepContentInputSchema: z.ZodObject<{
  */
 declare function createGrepContentTool(getFileSystemService: FileSystemServiceGetter): Tool<typeof GrepContentInputSchema>;
 
-export { type BufferEncoding, type CreateDirectoryOptions, type CreateDirectoryResult, type DeletePathOptions, type DeletePathResult, type DirectoryEntry, type EditFileOptions, type EditOperation, type EditResult, type FileContent, type FileMetadata, type FileSystemConfig, FileSystemError, FileSystemErrorCode, FileSystemService, type FileSystemServiceGetter, type FileSystemToolsConfig, FileSystemToolsConfigSchema, type GlobOptions, type GlobResult, type GrepOptions, type ListDirectoryOptions, type ListDirectoryResult, type PathValidation, PathValidator, type ReadFileOptions, type RenamePathResult, type SearchMatch, type SearchResult, type WriteFileOptions, type WriteResult, createEditFileTool, createGlobFilesTool, createGrepContentTool, createReadFileTool, createWriteFileTool, fileSystemToolsFactory };
+export { type BufferEncoding, type CreateDirectoryOptions, type CreateDirectoryResult, type DeletePathOptions, type DeletePathResult, type DirectoryEntry, type EditFileOptions, type EditOperation, type EditResult, type FileContent, type FileMetadata, type FileSystemConfig, FileSystemError, FileSystemErrorCode, FileSystemService, type FileSystemServiceGetter, type FileSystemToolsConfig, FileSystemToolsConfigSchema, type GlobOptions, type GlobResult, type GrepOptions, type ListDirectoryOptions, type ListDirectoryResult, type MediaFileContent, type PathValidation, PathValidator, type ReadFileOptions, type RenamePathResult, type SearchMatch, type SearchResult, type WriteFileOptions, type WriteResult, createEditFileTool, createGlobFilesTool, createGrepContentTool, createReadFileTool, createReadMediaFileTool, createWriteFileTool, fileSystemToolsFactory };

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * @dexto/tools-filesystem
  *
  * FileSystem tools factory for Dexto agents.
- * Provides file operation tools: read, write, edit, glob, grep.
+ * Provides file operation tools: read text, read media, write, edit, glob, grep.
  */
 export { fileSystemToolsFactory } from './tool-factory.js';
 export type { FileSystemServiceGetter } from './file-tool-types.js';
@@ -11,8 +11,9 @@ export { FileSystemService } from './filesystem-service.js';
 export { PathValidator } from './path-validator.js';
 export { FileSystemError } from './errors.js';
 export { FileSystemErrorCode } from './error-codes.js';
-export type { FileSystemConfig, FileContent, ReadFileOptions, GlobOptions, GlobResult, GrepOptions, SearchResult, SearchMatch, WriteFileOptions, WriteResult, EditFileOptions, EditResult, EditOperation, FileMetadata, DirectoryEntry, ListDirectoryOptions, ListDirectoryResult, CreateDirectoryOptions, CreateDirectoryResult, DeletePathOptions, DeletePathResult, RenamePathResult, PathValidation, BufferEncoding, } from './types.js';
+export type { FileSystemConfig, FileContent, MediaFileContent, ReadFileOptions, GlobOptions, GlobResult, GrepOptions, SearchResult, SearchMatch, WriteFileOptions, WriteResult, EditFileOptions, EditResult, EditOperation, FileMetadata, DirectoryEntry, ListDirectoryOptions, ListDirectoryResult, CreateDirectoryOptions, CreateDirectoryResult, DeletePathOptions, DeletePathResult, RenamePathResult, PathValidation, BufferEncoding, } from './types.js';
 export { createReadFileTool } from './read-file-tool.js';
+export { createReadMediaFileTool } from './read-media-file-tool.js';
 export { createWriteFileTool } from './write-file-tool.js';
 export { createEditFileTool } from './edit-file-tool.js';
 export { createGlobFilesTool } from './glob-files-tool.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,YAAY,EACR,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAGnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,YAAY,EACR,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,eAAe,EACf,UAAU,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,cAAc,GACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ import { PathValidator } from "./path-validator.js";
 import { FileSystemError } from "./errors.js";
 import { FileSystemErrorCode } from "./error-codes.js";
 import { createReadFileTool } from "./read-file-tool.js";
+import { createReadMediaFileTool } from "./read-media-file-tool.js";
 import { createWriteFileTool } from "./write-file-tool.js";
 import { createEditFileTool } from "./edit-file-tool.js";
 import { createGlobFilesTool } from "./glob-files-tool.js";
@@ -19,6 +20,7 @@ export {
   createGlobFilesTool,
   createGrepContentTool,
   createReadFileTool,
+  createReadMediaFileTool,
   createWriteFileTool,
   fileSystemToolsFactory
 };