repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

opencode/tools/image.ts

Raw
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, unknown>): 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<void> {
  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<string, unknown> = {};

      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),
      });
    }
  },
});