import { tool } from "@opencode-ai/plugin"; import sharp from "sharp"; import path from "node:path"; import { existsSync, mkdirSync, statSync } from "node:fs"; // ============================================================================ // Security Constants // ============================================================================ const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50MB const MAX_PIXELS = 100000000; // 100 megapixels const MAX_DIMENSION = 20000; // 20,000px const MAX_BASE64_SIZE = 10 * 1024 * 1024; // 10MB const SUPPORTED_FORMATS = [ "jpeg", "jpg", "png", "webp", "avif", "gif", "tiff", "heif", ] as const; // Supported sharp format type type SharpFormat = (typeof SUPPORTED_FORMATS)[number] extends infer T ? T extends "jpg" ? never : T : never; // ============================================================================ // Helper Functions // ============================================================================ /** * Create a JSON response string */ function jsonResponse(data: Record): string { return JSON.stringify(data, null, 2); } /** * Assert that a target path stays within the specified directory * Prevents path traversal attacks */ function assertWithinDirectory( targetPath: string, directory: string, operation: string, ): void { const resolvedTarget = path.resolve(targetPath); const resolvedDir = path.resolve(directory); const dirWithSep = resolvedDir.endsWith(path.sep) ? resolvedDir : resolvedDir + path.sep; if ( resolvedTarget !== resolvedDir && !resolvedTarget.startsWith(dirWithSep) ) { throw new Error( `Path security error: ${operation}: path escapes working directory: ${targetPath}`, ); } } /** * Check if input is a base64 data URI */ function isBase64DataUri(input: string): boolean { return input.startsWith("data:image/") && input.includes(";base64,"); } /** * Decode a base64 data URI to a Buffer */ function decodeBase64DataUri(uri: string): Buffer { const matches = uri.match(/^data:image\/(\w+);base64,(.+)$/); if (!matches || !matches[1] || !matches[2]) { throw new Error("Invalid base64 data URI format"); } const base64Data = matches[2]; // Check size limit if (base64Data.length > MAX_BASE64_SIZE * 1.37) { // Base64 is ~37% larger throw new Error( `Base64 data exceeds maximum size of ${MAX_BASE64_SIZE} bytes`, ); } return Buffer.from(base64Data, "base64"); } /** * Resolve a file path relative to the context directory */ function resolveFilePath(inputPath: string, directory: string): string { const trimmed = inputPath.trim(); const fullPath = path.resolve(directory, trimmed); assertWithinDirectory(fullPath, directory, "resolveFilePath"); return fullPath; } /** * Validate image dimensions */ function validateDimensions(width?: number, height?: number): string | null { if (width !== undefined) { if (width <= 0) { return "Width must be a positive number"; } if (width > MAX_DIMENSION) { return `Width exceeds maximum dimension of ${MAX_DIMENSION}px`; } } if (height !== undefined) { if (height <= 0) { return "Height must be a positive number"; } if (height > MAX_DIMENSION) { return `Height exceeds maximum dimension of ${MAX_DIMENSION}px`; } } if (width !== undefined && height !== undefined) { const pixels = width * height; if (pixels > MAX_PIXELS) { return `Image dimensions exceed maximum of ${MAX_PIXELS} pixels (${ MAX_PIXELS / 1000000 } megapixels)`; } } return null; } /** * Validate output format */ function validateFormat(format: string): string | null { const normalized = format.toLowerCase(); if ( !SUPPORTED_FORMATS.includes(normalized as typeof SUPPORTED_FORMATS[number]) ) { return `Invalid format: "${format}". Supported formats: ${ SUPPORTED_FORMATS.join(", ") }`; } return null; } /** * Validate blur/sharpen sigma */ function validateSigma(sigma: number): string | null { if (sigma < 0.3 || sigma > 1000) { return "Sigma must be between 0.3 and 1000"; } return null; } /** * Parse image input - accepts file path or base64 data URI */ async function parseImageInput( input: string, directory: string, ): Promise<{ buffer: Buffer | string; sourceType: "file" | "base64" }> { if (isBase64DataUri(input)) { return { buffer: decodeBase64DataUri(input), sourceType: "base64", }; } const fullPath = resolveFilePath(input, directory); if (!existsSync(fullPath)) { throw new Error(`Image not found: ${input}`); } const stats = statSync(fullPath); if (stats.size > MAX_FILE_SIZE) { throw new Error( `Image file exceeds maximum size of ${MAX_FILE_SIZE / 1024 / 1024}MB`, ); } return { buffer: fullPath, sourceType: "file", }; } /** * Validate image metadata against security constraints */ async function validateImageSecurity( imagePathOrBuffer: Buffer | string, ): Promise { const metadata = await sharp(imagePathOrBuffer).metadata(); if (metadata.width && metadata.width > MAX_DIMENSION) { throw new Error( `Image width (${metadata.width}px) exceeds maximum of ${MAX_DIMENSION}px`, ); } if (metadata.height && metadata.height > MAX_DIMENSION) { throw new Error( `Image height (${metadata.height}px) exceeds maximum of ${MAX_DIMENSION}px`, ); } if (metadata.width && metadata.height) { const pixels = metadata.width * metadata.height; if (pixels > MAX_PIXELS) { throw new Error( `Image (${pixels} pixels) exceeds maximum of ${MAX_PIXELS} pixels`, ); } } } /** * Determine output path for processed image */ function determineOutputPath( inputPath: string | null, suffix: string, format: string, directory: string, ): string { const outputDir = path.join(directory, ".output"); // Ensure output directory exists if (!existsSync(outputDir)) { mkdirSync(outputDir, { recursive: true }); } if (inputPath) { const baseName = path.basename(inputPath, path.extname(inputPath)); return path.join(outputDir, `${baseName}${suffix}.${format}`); } const timestamp = Date.now(); return path.join(outputDir, `image${suffix}-${timestamp}.${format}`); } /** * Get format from metadata or default to jpeg */ function getFormatFromMetadata(metadata: sharp.Metadata): SharpFormat { if (metadata.format) { const normalized = metadata.format === "jpg" ? "jpeg" : metadata.format; if ( SUPPORTED_FORMATS.includes(normalized as typeof SUPPORTED_FORMATS[number]) ) { return normalized as SharpFormat; } } return "jpeg"; } /** * Format file size for human readability */ function formatFileSize(bytes: number): string { const units = ["B", "KB", "MB", "GB"]; let size = bytes; let unitIndex = 0; while (size >= 1024 && unitIndex < units.length - 1) { size /= 1024; unitIndex++; } return `${size.toFixed(2)} ${units[unitIndex]}`; } /** * Extract error message from unknown error */ function getErrorMessage(err: unknown): string { if (err instanceof Error) { return err.message; } return String(err); } // ============================================================================ // Tool 1: image_resize // ============================================================================ export const image_resize = tool({ description: `Resize an image with various fit options and interpolation kernels. Fit options: - cover: Crop to fill both dimensions (default) - contain: Fit within dimensions, may add letterboxing - fill: Ignore aspect ratio, stretch to exact dimensions - inside: Fit within dimensions without cropping - outside: Fill dimensions, may exceed bounds Kernel options: - nearest: Fastest, pixelated results - cubic: Good balance of speed and quality - mitchell: High quality, slower - lanczos2: High quality, good for downscaling - lanczos3: Highest quality, slowest (default) Examples: - Resize to 800x600 with cover fit: image_resize({ input: "photo.jpg", width: 800, height: 600 }) - Resize maintaining aspect ratio: image_resize({ input: "photo.jpg", width: 800 }) - Prevent upscaling: image_resize({ input: "photo.jpg", width: 800, withoutEnlargement: true }) - Return as base64: image_resize({ input: "photo.jpg", width: 800, returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), width: tool.schema .number() .optional() .describe( "Target width in pixels. Omit to auto-scale based on height.", ), height: tool.schema .number() .optional() .describe( "Target height in pixels. Omit to auto-scale based on width.", ), fit: tool.schema .enum(["cover", "contain", "fill", "inside", "outside"]) .default("cover") .describe("How the image should fit the dimensions. Default: cover"), position: tool.schema .string() .default("center") .describe( "Position for cropping (cover/contain): center, top, bottom, left, right, etc. Default: center", ), kernel: tool.schema .enum(["nearest", "cubic", "mitchell", "lanczos2", "lanczos3"]) .default("lanczos3") .describe("Interpolation kernel for resizing. Default: lanczos3"), withoutEnlargement: tool.schema .boolean() .default(false) .describe( "Do not upscale if image is smaller than target dimensions", ), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Validate dimensions const dimError = validateDimensions(args.width, args.height); if (dimError) { return jsonResponse({ success: false, error: `Validation error: ${dimError}`, }); } if (!args.width && !args.height) { return jsonResponse({ success: false, error: "Validation error: At least one of width or height must be specified", }); } // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); // Build resize options const resizeOptions: sharp.ResizeOptions = { width: args.width, height: args.height, fit: args.fit as sharp.FitEnum[keyof sharp.FitEnum], position: args.position as sharp.Gravity, kernel: args.kernel as sharp.KernelEnum[keyof sharp.KernelEnum], withoutEnlargement: args.withoutEnlargement, }; let pipeline = sharp(buffer).resize(resizeOptions); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "resize", data: `data:image/${format};base64,${base64}`, format, width: args.width, height: args.height, fit: args.fit, }); } // Save to file const suffix = args.width && args.height ? `-resize-${args.width}x${args.height}` : args.width ? `-resize-${args.width}w` : `-resize-${args.height}h`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); const outputMeta = await sharp(outputPath).metadata(); return jsonResponse({ success: true, operation: "resize", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, width: outputMeta.width, height: outputMeta.height, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), options: { width: args.width, height: args.height, fit: args.fit, position: args.position, kernel: args.kernel, withoutEnlargement: args.withoutEnlargement, }, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 2: image_crop // ============================================================================ export const image_crop = tool({ description: `Extract a rectangular region from an image. Specify the region using left, top coordinates (top-left corner) and dimensions. Examples: - Extract 200x150 region starting at (100, 50): image_crop({ input: "photo.jpg", left: 100, top: 50, width: 200, height: 150 }) - Crop from top-left corner: image_crop({ input: "photo.jpg", left: 0, top: 0, width: 500, height: 500 }) - Return as base64: image_crop({ input: "photo.jpg", left: 100, top: 100, width: 300, height: 200, returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), left: tool.schema .number() .describe( "Left offset (x-coordinate) in pixels from the top-left corner", ), top: tool.schema .number() .describe( "Top offset (y-coordinate) in pixels from the top-left corner", ), width: tool.schema .number() .describe("Width of the region to extract in pixels"), height: tool.schema .number() .describe("Height of the region to extract in pixels"), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Validate crop parameters if (args.left < 0 || args.top < 0) { return jsonResponse({ success: false, error: "Validation error: Left and top coordinates must be non-negative", }); } const dimError = validateDimensions(args.width, args.height); if (dimError) { return jsonResponse({ success: false, error: `Validation error: ${dimError}`, }); } // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); // Perform crop const pipeline = sharp(buffer).extract({ left: args.left, top: args.top, width: args.width, height: args.height, }); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "crop", data: `data:image/${format};base64,${base64}`, format, region: { left: args.left, top: args.top, width: args.width, height: args.height, }, }); } // Save to file const suffix = `-crop-${args.width}x${args.height}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "crop", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), region: { left: args.left, top: args.top, width: args.width, height: args.height, }, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 3: image_rotate // ============================================================================ export const image_rotate = tool({ description: `Rotate an image by a specified angle. Rotation angles are clockwise. Common angles: 90, 180, 270. For arbitrary angles, a background color can be specified for areas not covered by the rotated image. Examples: - Rotate 90 degrees clockwise: image_rotate({ input: "photo.jpg", angle: 90 }) - Rotate 180 degrees: image_rotate({ input: "photo.jpg", angle: 180 }) - Rotate 45 degrees with white background: image_rotate({ input: "photo.jpg", angle: 45, background: "#ffffff" }) - Return as base64: image_rotate({ input: "photo.jpg", angle: 90, returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), angle: tool.schema .number() .describe("Rotation angle in degrees (clockwise)"), background: tool.schema .string() .optional() .describe( 'Background color for non-rectangular rotations (CSS color string, e.g., "#ffffff", "rgba(0,0,0,0.5)"). Default: transparent', ), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); // Build rotate options const rotateOptions: sharp.RotateOptions = {}; if (args.background) { rotateOptions.background = args.background; } const pipeline = sharp(buffer).rotate(args.angle, rotateOptions); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "rotate", data: `data:image/${format};base64,${base64}`, format, angle: args.angle, }); } // Save to file const suffix = `-rotate-${args.angle}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); const outputMeta = await sharp(outputPath).metadata(); return jsonResponse({ success: true, operation: "rotate", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, width: outputMeta.width, height: outputMeta.height, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), angle: args.angle, background: args.background || "transparent", }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 4: image_flip // ============================================================================ export const image_flip = tool({ description: `Flip an image horizontally (flop), vertically (flip), or both. Examples: - Flip horizontally (mirror left-right): image_flip({ input: "photo.jpg", horizontal: true }) - Flip vertically (mirror top-bottom): image_flip({ input: "photo.jpg", vertical: true }) - Flip both axes: image_flip({ input: "photo.jpg", horizontal: true, vertical: true }) - Return as base64: image_flip({ input: "photo.jpg", horizontal: true, returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), vertical: tool.schema .boolean() .default(false) .describe("Flip vertically (mirror top-bottom)"), horizontal: tool.schema .boolean() .default(false) .describe("Flip horizontally (mirror left-right)"), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { if (!args.vertical && !args.horizontal) { return jsonResponse({ success: false, error: "Validation error: At least one of vertical or horizontal must be true", }); } // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); let pipeline = sharp(buffer); if (args.vertical) { pipeline = pipeline.flip(); } if (args.horizontal) { pipeline = pipeline.flop(); } if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "flip", data: `data:image/${format};base64,${base64}`, format, vertical: args.vertical, horizontal: args.horizontal, }); } // Save to file const flipType: string[] = []; if (args.vertical) flipType.push("v"); if (args.horizontal) flipType.push("h"); const suffix = `-flip-${flipType.join("")}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "flip", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), vertical: args.vertical, horizontal: args.horizontal, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 5: image_grayscale // ============================================================================ export const image_grayscale = tool({ description: `Convert an image to grayscale (black and white). Examples: - Convert to grayscale: image_grayscale({ input: "photo.jpg" }) - Return as base64: image_grayscale({ input: "photo.jpg", returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); const pipeline = sharp(buffer).grayscale(); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "grayscale", data: `data:image/${format};base64,${base64}`, format, }); } // Save to file const suffix = "-grayscale"; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "grayscale", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 6: image_blur // ============================================================================ export const image_blur = tool({ description: `Apply Gaussian blur to an image. The sigma parameter controls the strength of the blur effect. Higher values produce more blur. Range: 0.3 to 1000. Typical values: 1-20 for visible blur. Examples: - Light blur: image_blur({ input: "photo.jpg", sigma: 3 }) - Heavy blur: image_blur({ input: "photo.jpg", sigma: 15 }) - Return as base64: image_blur({ input: "photo.jpg", sigma: 5, returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), sigma: tool.schema .number() .min(0.3) .max(1000) .describe( "Blur radius (sigma). Range: 0.3-1000. Higher = more blur.", ), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Validate sigma const sigmaError = validateSigma(args.sigma); if (sigmaError) { return jsonResponse({ success: false, error: `Validation error: ${sigmaError}`, }); } // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); const pipeline = sharp(buffer).blur(args.sigma); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "blur", data: `data:image/${format};base64,${base64}`, format, sigma: args.sigma, }); } // Save to file const suffix = `-blur-${args.sigma}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "blur", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), sigma: args.sigma, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 7: image_sharpen // ============================================================================ export const image_sharpen = tool({ description: `Sharpen an image to enhance edges and details. Uses unsharp masking with configurable parameters: - sigma: Gaussian mask sigma (sharpness radius) - flat: Amount of sharpening for flat areas - jagged: Amount of sharpening for edge areas Examples: - Standard sharpen: image_sharpen({ input: "photo.jpg" }) - Strong sharpen: image_sharpen({ input: "photo.jpg", sigma: 2, flat: 2, jagged: 4 }) - Return as base64: image_sharpen({ input: "photo.jpg", returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), sigma: tool.schema .number() .default(1) .describe("Gaussian mask sigma. Default: 1"), flat: tool.schema .number() .default(1) .describe( "Amount of sharpening to apply to flat areas. Default: 1", ), jagged: tool.schema .number() .default(2) .describe( "Amount of sharpening to apply to edge areas. Default: 2", ), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get metadata for format detection const metadata = await sharp(buffer).metadata(); const format = getFormatFromMetadata(metadata); const pipeline = sharp(buffer).sharpen({ sigma: args.sigma, m1: args.flat, m2: args.jagged, }); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "sharpen", data: `data:image/${format};base64,${base64}`, format, sigma: args.sigma, flat: args.flat, jagged: args.jagged, }); } // Save to file const suffix = `-sharpen-${args.sigma}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "sharpen", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), sigma: args.sigma, flat: args.flat, jagged: args.jagged, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 8: image_convert // ============================================================================ export const image_convert = tool({ description: `Convert an image from one format to another. Supported formats: jpeg, png, webp, avif, tiff, gif, heif Format-specific options: - quality: Quality for lossy formats (1-100) - lossless: Use lossless compression (webp, avif only) - compressionLevel: PNG compression level (0-9, higher = smaller) Examples: - Convert to WebP: image_convert({ input: "photo.png", format: "webp" }) - Convert to AVIF with quality: image_convert({ input: "photo.jpg", format: "avif", quality: 90 }) - Convert to lossless WebP: image_convert({ input: "photo.png", format: "webp", lossless: true }) - Return as base64: image_convert({ input: "photo.jpg", format: "png", returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), format: tool.schema .enum(["jpeg", "png", "webp", "avif", "tiff", "gif", "heif"]) .describe("Target output format"), quality: tool.schema .number() .min(1) .max(100) .default(80) .describe("Quality for lossy formats (1-100). Default: 80"), lossless: tool.schema .boolean() .default(false) .describe("Use lossless compression (webp, avif only)"), compressionLevel: tool.schema .number() .min(0) .max(9) .default(6) .describe("PNG compression level (0-9). Default: 6"), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Validate format const formatError = validateFormat(args.format); if (formatError) { return jsonResponse({ success: false, error: `Validation error: ${formatError}`, }); } // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Get input metadata const inputMetadata = await sharp(buffer).metadata(); // Build format options const formatOptions: Record = {}; switch (args.format) { case "jpeg": formatOptions.quality = args.quality; formatOptions.mozjpeg = true; break; case "png": formatOptions.compressionLevel = args.compressionLevel; break; case "webp": case "avif": if (args.lossless) { formatOptions.lossless = true; } else { formatOptions.quality = args.quality; } break; case "tiff": formatOptions.quality = args.quality; break; case "gif": // GIF doesn't have quality option break; case "heif": formatOptions.quality = args.quality; break; } const pipeline = sharp(buffer).toFormat( args.format as SharpFormat, formatOptions, ); if (args.returnBase64) { const outputBuffer = await pipeline.toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "convert", data: `data:image/${args.format};base64,${base64}`, format: args.format, from_format: inputMetadata.format, }); } // Save to file const suffix = `-converted`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, args.format, context.directory, ); await pipeline.toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "convert", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), from_format: inputMetadata.format, to_format: args.format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), quality: args.quality, lossless: args.lossless, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 9: image_metadata // ============================================================================ export const image_metadata = tool({ description: `Get comprehensive metadata from an image file. Returns detailed information including: - Dimensions (width, height) - Format (jpeg, png, webp, etc.) - Color channels and space - Density (DPI) - Alpha channel presence - Orientation - Depth and more Examples: - Get metadata: image_metadata({ input: "photo.jpg" }) - Get metadata from base64: image_metadata({ input: "data:image/png;base64,..." })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), }, async execute(args, context) { try { // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Get metadata const metadata = await sharp(buffer).metadata(); let fileSize: number | undefined; if (sourceType === "file") { const fullPath = resolveFilePath(args.input, context.directory); const stats = statSync(fullPath); fileSize = stats.size; } return jsonResponse({ success: true, operation: "metadata", input: sourceType === "file" ? args.input : "(base64 data)", metadata: { format: metadata.format, width: metadata.width, height: metadata.height, channels: metadata.channels, space: metadata.space, depth: metadata.depth, density: metadata.density, hasAlpha: metadata.hasAlpha, isProgressive: metadata.isProgressive, orientation: metadata.orientation, size: fileSize, size_human: fileSize ? formatFileSize(fileSize) : undefined, }, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 10: image_composite // ============================================================================ export const image_composite = tool({ description: `Composite (overlay) one image on top of another. Blend modes: - over: Standard alpha blending (default) - multiply: Multiply colors - screen: Screen blend - overlay: Overlay blend - darken: Keep darker pixels - lighten: Keep lighter pixels - colorDodge: Color dodge - colorBurn: Color burn - hardLight: Hard light - softLight: Soft light - difference: Difference - exclusion: Exclusion Examples: - Simple overlay: image_composite({ base: "background.jpg", overlay: "logo.png", x: 10, y: 10 }) - Centered overlay: image_composite({ base: "photo.jpg", overlay: "watermark.png", x: 100, y: 100 }) - With blend mode: image_composite({ base: "photo.jpg", overlay: "texture.png", x: 0, y: 0, blend: "multiply" }) - Return as base64: image_composite({ base: "photo.jpg", overlay: "logo.png", x: 10, y: 10, returnBase64: true })`, args: { base: tool.schema .string() .describe( "Base image file path (relative to working directory) or base64 data URI", ), overlay: tool.schema .string() .describe( "Overlay image file path (relative to working directory) or base64 data URI", ), x: tool.schema .number() .describe("X position for overlay (pixels from left)"), y: tool.schema .number() .describe("Y position for overlay (pixels from top)"), blend: tool.schema .enum([ "over", "multiply", "screen", "overlay", "darken", "lighten", "colorDodge", "colorBurn", "hardLight", "softLight", "difference", "exclusion", ]) .default("over") .describe("Blend mode. Default: over"), opacity: tool.schema .number() .min(0) .max(1) .default(1) .describe("Overlay opacity (0-1). Default: 1 (fully opaque)"), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Parse base image const { buffer: baseBuffer, sourceType: baseSourceType } = await parseImageInput(args.base, context.directory); // Validate security await validateImageSecurity(baseBuffer); // Parse overlay image const { buffer: overlayBuffer } = await parseImageInput( args.overlay, context.directory, ); // Validate overlay security await validateImageSecurity(overlayBuffer); // Get metadata for format detection const metadata = await sharp(baseBuffer).metadata(); const format = getFormatFromMetadata(metadata); // Prepare overlay with opacity if needed let overlayInput: Buffer | string = overlayBuffer; if (args.opacity < 1) { // Create a semi-transparent version of the overlay using modulate // We use a different approach: flatten alpha and re-apply with desired opacity const overlayMeta = await sharp(overlayBuffer).metadata(); if (overlayMeta.hasAlpha) { // Extract alpha channel and modulate it const alphaChannel = await sharp(overlayBuffer) .extractChannel("alpha") .toBuffer(); // Create modulated alpha with reduced opacity const modulatedAlpha = await sharp(alphaChannel) .modulate({ brightness: args.opacity }) .toBuffer(); // Rebuild image with modulated alpha const rgbBuffer = await sharp(overlayBuffer) .removeAlpha() .toBuffer(); overlayInput = await sharp(rgbBuffer) .joinChannel(modulatedAlpha) .toBuffer(); } else { // If no alpha, add one with the desired opacity overlayInput = await sharp(overlayBuffer) .ensureAlpha(args.opacity) .toBuffer(); } } const pipeline = sharp(baseBuffer).composite([ { input: overlayInput, left: args.x, top: args.y, blend: args.blend as sharp.Blend, }, ]); if (args.returnBase64) { const outputBuffer = await pipeline .toFormat(format) .toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "composite", data: `data:image/${format};base64,${base64}`, format, position: { x: args.x, y: args.y }, blend: args.blend, opacity: args.opacity, }); } // Save to file const suffix = "-composite"; const outputPath = determineOutputPath( baseSourceType === "file" ? args.base : null, suffix, format, context.directory, ); await pipeline.toFormat(format).toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "composite", input: baseSourceType === "file" ? args.base : "(base64 data)", overlay: args.overlay, output: path.relative(context.directory, outputPath), format, size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), position: { x: args.x, y: args.y }, blend: args.blend, opacity: args.opacity, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, }); // ============================================================================ // Tool 11: image_channel // ============================================================================ export const image_channel = tool({ description: `Extract a single color channel from an image. Channels: - red: Red channel - green: Green channel - blue: Blue channel - alpha: Alpha (transparency) channel The result is a grayscale image representing the selected channel's intensity. Examples: - Extract red channel: image_channel({ input: "photo.jpg", channel: "red" }) - Extract alpha channel: image_channel({ input: "photo.png", channel: "alpha" }) - Return as base64: image_channel({ input: "photo.jpg", channel: "green", returnBase64: true })`, args: { input: tool.schema .string() .describe( "Image file path (relative to working directory) or base64 data URI", ), channel: tool.schema .enum(["red", "green", "blue", "alpha"]) .describe("Channel to extract"), returnBase64: tool.schema .boolean() .default(false) .describe("Return base64 data URI instead of file path"), }, async execute(args, context) { try { // Parse input const { buffer, sourceType } = await parseImageInput( args.input, context.directory, ); // Validate security await validateImageSecurity(buffer); // Extract channel const pipeline = sharp(buffer).extractChannel(args.channel); if (args.returnBase64) { const outputBuffer = await pipeline.png().toBuffer(); const base64 = outputBuffer.toString("base64"); return jsonResponse({ success: true, operation: "channel", data: `data:image/png;base64,${base64}`, format: "png", channel: args.channel, }); } // Save to file const suffix = `-channel-${args.channel}`; const outputPath = determineOutputPath( sourceType === "file" ? args.input : null, suffix, "png", context.directory, ); await pipeline.png().toFile(outputPath); const outputStats = statSync(outputPath); return jsonResponse({ success: true, operation: "channel", input: sourceType === "file" ? args.input : "(base64 data)", output: path.relative(context.directory, outputPath), format: "png", size_bytes: outputStats.size, size_human: formatFileSize(outputStats.size), channel: args.channel, }); } catch (err) { return jsonResponse({ success: false, error: getErrorMessage(err), }); } }, });