@agent-webui/ai-desk-harness-gimp 1.0.29-beta1

package/README.md

@@ -0,0 +1,4 @@
+# @agent-webui/ai-desk-harness-gimp
+
+Vendored `gimp/agent-harness` package from `HKUDS/CLI-Anything`, packaged for
+AI Desk installation flows.

package/manifest.json

@@ -0,0 +1,22 @@
+{
+  "name": "gimp",
+  "display_name": "CLI-Anything GIMP Harness",
+  "module": "cli_anything.gimp",
+  "version": "1.0.0",
+  "source_path": "python/agent-harness",
+  "commands": [
+    "cli-anything-gimp"
+  ],
+  "python_requirements": [
+    "numpy>=2.0.0"
+  ],
+  "capabilities": [
+    "json-output",
+    "repl-mode",
+    "agent-native"
+  ],
+  "upstream": {
+    "repository": "https://github.com/HKUDS/CLI-Anything",
+    "subpath": "gimp/agent-harness"
+  }
+}

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@agent-webui/ai-desk-harness-gimp",
+  "version": "1.0.29-beta1",
+  "description": "Vendored CLI-Anything GIMP harness for AI Desk",
+  "files": [
+    "manifest.json",
+    "python/agent-harness/",
+    "README.md"
+  ],
+  "license": "MIT"
+}

package/python/agent-harness/GIMP.md

@@ -0,0 +1,301 @@
+# GIMP: Project-Specific Analysis & SOP
+
+## Architecture Summary
+
+GIMP (GNU Image Manipulation Program) is a GTK-based raster image editor built on
+the **GEGL** (Generic Graphics Library) processing engine and **Babl** color management.
+
+```
+┌──────────────────────────────────────────────┐
+│                  GIMP GUI                    │
+│  ┌──────────┐ ┌──────────┐ ┌─────────────┐  │
+│  │  Canvas   │ │  Layers  │ │   Filters   │  │
+│  │  (GTK)    │ │  (GTK)   │ │   (GTK)     │  │
+│  └────┬──────┘ └────┬─────┘ └──────┬──────┘  │
+│       │             │              │          │
+│  ┌────┴─────────────┴──────────────┴───────┐ │
+│  │       PDB (Procedure Database)          │ │
+│  │  500+ registered procedures for all     │ │
+│  │  image operations, filters, I/O         │ │
+│  └─────────────────┬───────────────────────┘ │
+│                    │                          │
+│  ┌─────────────────┴───────────────────────┐ │
+│  │       GEGL Processing Engine            │ │
+│  │  DAG-based image processing pipeline    │ │
+│  │  70+ built-in operations               │ │
+│  └─────────────────┬───────────────────────┘ │
+└────────────────────┼─────────────────────────┘
+                     │
+         ┌───────────┴──────────┐
+         │  Babl (color mgmt)   │
+         │  + GEGL operations   │
+         │  + File format I/O   │
+         └──────────────────────┘
+```
+
+## CLI Strategy: Pillow + External Tools
+
+Unlike Shotcut (which manipulates XML project files), GIMP's native .xcf format
+is a complex binary format. Our strategy:
+
+1. **Pillow** — Python's standard imaging library. Handles image I/O (PNG, JPEG,
+   TIFF, BMP, GIF, WebP, etc.), pixel manipulation, basic filters, color
+   adjustments, drawing, and compositing. This is our primary engine.
+2. **GEGL CLI** — If available, use `gegl` command for advanced operations.
+3. **GIMP batch mode** — If `gimp` is installed, use `gimp -i -b` for XCF
+   operations and advanced filters via Script-Fu/Python-Fu.
+
+### Why Not XCF Directly?
+
+XCF is a tile-based binary format with compression, layers, channels, paths,
+and GEGL filter graphs. Parsing it from scratch is extremely complex (5000+ lines
+of C in GIMP's xcf-load.c). Instead:
+- For new projects, we build layer stacks in memory using Pillow
+- For XCF import/export, we delegate to GIMP batch mode if available
+- Our "project file" is a JSON manifest tracking layers, operations, and history
+
+## The Project Format (.gimp-cli.json)
+
+Since we can't easily manipulate XCF directly, we use a JSON project format:
+
+```json
+{
+  "version": "1.0",
+  "name": "my_project",
+  "canvas": {
+    "width": 1920,
+    "height": 1080,
+    "color_mode": "RGB",
+    "background": "#ffffff",
+    "dpi": 300
+  },
+  "layers": [
+    {
+      "id": 0,
+      "name": "Background",
+      "type": "image",
+      "source": "/path/to/image.png",
+      "visible": true,
+      "opacity": 1.0,
+      "blend_mode": "normal",
+      "offset_x": 0,
+      "offset_y": 0,
+      "filters": [
+        {"name": "brightness", "params": {"factor": 1.2}},
+        {"name": "gaussian_blur", "params": {"radius": 3}}
+      ]
+    },
+    {
+      "id": 1,
+      "name": "Text Layer",
+      "type": "text",
+      "text": "Hello World",
+      "font": "Arial",
+      "font_size": 48,
+      "color": "#000000",
+      "visible": true,
+      "opacity": 0.8,
+      "blend_mode": "normal",
+      "offset_x": 100,
+      "offset_y": 50,
+      "filters": []
+    }
+  ],
+  "selection": null,
+  "guides": [],
+  "metadata": {}
+}
+```
+
+## Core Operations via Pillow
+
+### Image I/O
+| Operation | Pillow API |
+|-----------|-----------|
+| Open image | `Image.open(path)` |
+| Save image | `image.save(path, format)` |
+| Create blank | `Image.new(mode, (w,h), color)` |
+| Convert mode | `image.convert("RGB"/"L"/"RGBA")` |
+| Resize | `image.resize((w,h), resample)` |
+| Crop | `image.crop((l, t, r, b))` |
+| Rotate | `image.rotate(angle, expand=True)` |
+| Flip | `image.transpose(Image.FLIP_LEFT_RIGHT)` |
+
+### Filters & Adjustments
+| Operation | Pillow API |
+|-----------|-----------|
+| Brightness | `ImageEnhance.Brightness(img).enhance(factor)` |
+| Contrast | `ImageEnhance.Contrast(img).enhance(factor)` |
+| Saturation | `ImageEnhance.Color(img).enhance(factor)` |
+| Sharpness | `ImageEnhance.Sharpness(img).enhance(factor)` |
+| Gaussian blur | `image.filter(ImageFilter.GaussianBlur(radius))` |
+| Box blur | `image.filter(ImageFilter.BoxBlur(radius))` |
+| Unsharp mask | `image.filter(ImageFilter.UnsharpMask(radius, percent, threshold))` |
+| Find edges | `image.filter(ImageFilter.FIND_EDGES)` |
+| Emboss | `image.filter(ImageFilter.EMBOSS)` |
+| Contour | `image.filter(ImageFilter.CONTOUR)` |
+| Detail | `image.filter(ImageFilter.DETAIL)` |
+| Smooth | `image.filter(ImageFilter.SMOOTH_MORE)` |
+| Grayscale | `ImageOps.grayscale(image)` |
+| Invert | `ImageOps.invert(image)` |
+| Posterize | `ImageOps.posterize(image, bits)` |
+| Solarize | `ImageOps.solarize(image, threshold)` |
+| Autocontrast | `ImageOps.autocontrast(image)` |
+| Equalize | `ImageOps.equalize(image)` |
+| Sepia | Custom kernel via `ImageOps.colorize()` |
+
+### Compositing & Drawing
+| Operation | Pillow API |
+|-----------|-----------|
+| Paste layer | `Image.alpha_composite(base, overlay)` |
+| Blend modes | Custom implementations (multiply, screen, overlay, etc.) |
+| Draw rectangle | `ImageDraw.rectangle(xy, fill, outline)` |
+| Draw ellipse | `ImageDraw.ellipse(xy, fill, outline)` |
+| Draw text | `ImageDraw.text(xy, text, font, fill)` |
+| Draw line | `ImageDraw.line(xy, fill, width)` |
+
+## Blend Modes
+
+Pillow doesn't natively support Photoshop/GIMP blend modes. We implement the
+most common ones using NumPy-style pixel math:
+
+| Mode | Formula |
+|------|---------|
+| Normal | `top` (with alpha compositing) |
+| Multiply | `base * top / 255` |
+| Screen | `255 - (255-base)*(255-top)/255` |
+| Overlay | `if base < 128: 2*base*top/255 else: 255 - 2*(255-base)*(255-top)/255` |
+| Soft Light | Photoshop-style formula |
+| Hard Light | Overlay with base/top swapped |
+| Difference | `abs(base - top)` |
+| Darken | `min(base, top)` |
+| Lighten | `max(base, top)` |
+| Color Dodge | `base / (255 - top) * 255` |
+| Color Burn | `255 - (255-base) / top * 255` |
+
+## Command Map: GUI Action -> CLI Command
+
+| GUI Action | CLI Command |
+|-----------|-------------|
+| File -> New | `project new --width 1920 --height 1080 [--mode RGB]` |
+| File -> Open | `project open <path>` |
+| File -> Save | `project save [path]` |
+| File -> Export As | `export render <output> [--format png] [--quality 95]` |
+| Image -> Canvas Size | `canvas resize --width W --height H` |
+| Image -> Scale Image | `canvas scale --width W --height H` |
+| Image -> Crop to Selection | `canvas crop --left L --top T --right R --bottom B` |
+| Image -> Mode -> RGB | `canvas mode RGB` |
+| Layer -> New Layer | `layer new [--name "Layer"] [--width W] [--height H]` |
+| Layer -> Duplicate | `layer duplicate <index>` |
+| Layer -> Delete | `layer remove <index>` |
+| Layer -> Flatten Image | `layer flatten` |
+| Layer -> Merge Down | `layer merge-down <index>` |
+| Move layer | `layer move <index> --to <position>` |
+| Set layer opacity | `layer set <index> opacity <value>` |
+| Set blend mode | `layer set <index> mode <mode>` |
+| Toggle visibility | `layer set <index> visible <true/false>` |
+| Layer -> Add from File | `layer add-from-file <path> [--name N] [--position P]` |
+| Filters -> Blur -> Gaussian | `filter add gaussian_blur --layer L --param radius=5` |
+| Colors -> Brightness-Contrast | `filter add brightness --layer L --param factor=1.2` |
+| Colors -> Hue-Saturation | `filter add saturation --layer L --param factor=1.3` |
+| Colors -> Invert | `filter add invert --layer L` |
+| Draw text on layer | `draw text --layer L --text "Hi" --x 10 --y 10 --font Arial --size 24` |
+| Draw rectangle | `draw rect --layer L --x1 0 --y1 0 --x2 100 --y2 100 --fill "#ff0000"` |
+| View layers | `layer list` |
+| View project info | `project info` |
+| Undo | `session undo` |
+| Redo | `session redo` |
+
+## Filter Registry
+
+### Image Adjustments
+| CLI Name | Pillow Implementation | Key Parameters |
+|----------|----------------------|----------------|
+| `brightness` | `ImageEnhance.Brightness` | `factor` (1.0 = neutral, >1 = brighter) |
+| `contrast` | `ImageEnhance.Contrast` | `factor` (1.0 = neutral) |
+| `saturation` | `ImageEnhance.Color` | `factor` (1.0 = neutral, 0 = grayscale) |
+| `sharpness` | `ImageEnhance.Sharpness` | `factor` (1.0 = neutral, >1 = sharper) |
+| `autocontrast` | `ImageOps.autocontrast` | `cutoff` (0-49, percent to clip) |
+| `equalize` | `ImageOps.equalize` | (no params) |
+| `invert` | `ImageOps.invert` | (no params) |
+| `posterize` | `ImageOps.posterize` | `bits` (1-8) |
+| `solarize` | `ImageOps.solarize` | `threshold` (0-255) |
+| `grayscale` | `ImageOps.grayscale` | (no params) |
+| `sepia` | Custom colorize | `strength` (0.0-1.0) |
+
+### Blur & Sharpen
+| CLI Name | Pillow Implementation | Key Parameters |
+|----------|----------------------|----------------|
+| `gaussian_blur` | `ImageFilter.GaussianBlur` | `radius` (pixels) |
+| `box_blur` | `ImageFilter.BoxBlur` | `radius` (pixels) |
+| `unsharp_mask` | `ImageFilter.UnsharpMask` | `radius`, `percent`, `threshold` |
+| `smooth` | `ImageFilter.SMOOTH_MORE` | (no params) |
+
+### Stylize
+| CLI Name | Pillow Implementation | Key Parameters |
+|----------|----------------------|----------------|
+| `find_edges` | `ImageFilter.FIND_EDGES` | (no params) |
+| `emboss` | `ImageFilter.EMBOSS` | (no params) |
+| `contour` | `ImageFilter.CONTOUR` | (no params) |
+| `detail` | `ImageFilter.DETAIL` | (no params) |
+
+### Transform
+| CLI Name | Pillow Implementation | Key Parameters |
+|----------|----------------------|----------------|
+| `rotate` | `Image.rotate` | `angle` (degrees), `expand` (bool) |
+| `flip_h` | `Image.transpose(FLIP_LEFT_RIGHT)` | (no params) |
+| `flip_v` | `Image.transpose(FLIP_TOP_BOTTOM)` | (no params) |
+| `resize` | `Image.resize` | `width`, `height`, `resample` (nearest/bilinear/bicubic/lanczos) |
+| `crop` | `Image.crop` | `left`, `top`, `right`, `bottom` |
+
+## Export Formats
+
+| Format | Extension | Quality Param | Notes |
+|--------|-----------|---------------|-------|
+| PNG | .png | `compress_level` (0-9) | Lossless, supports alpha |
+| JPEG | .jpg/.jpeg | `quality` (1-95) | Lossy, no alpha |
+| WebP | .webp | `quality` (1-100) | Both lossy/lossless |
+| TIFF | .tiff | `compression` (none/lzw/jpeg) | Professional |
+| BMP | .bmp | (none) | Uncompressed |
+| GIF | .gif | (none) | 256 colors max |
+| ICO | .ico | (none) | Icon format |
+| PDF | .pdf | (none) | Multi-page possible |
+
+## Rendering Pipeline
+
+For GIMP CLI, "rendering" means flattening the layer stack with all filters
+applied and exporting to a target format.
+
+### Pipeline Steps:
+1. Start with canvas (background color or transparent)
+2. For each visible layer (bottom to top):
+   a. Load/create the layer content
+   b. Apply all layer filters in order
+   c. Position at layer offset
+   d. Composite onto canvas using blend mode and opacity
+3. Export final composited image
+
+### Rendering Gap Assessment: **Medium**
+- Most operations (resize, crop, filters, compositing) work via Pillow directly
+- Advanced GEGL operations (high-pass filter, wavelet decompose) not available
+- No XCF round-trip without GIMP installed
+- Blend modes require custom implementation but are mathematically straightforward
+
+## Test Coverage Plan
+
+1. **Unit tests** (`test_core.py`): Synthetic data, no real images needed
+   - Project create/open/save/info
+   - Layer add/remove/reorder/properties
+   - Filter application and parameter validation
+   - Canvas operations (resize, scale, crop, mode conversion)
+   - Session undo/redo
+   - JSON project serialization/deserialization
+
+2. **E2E tests** (`test_full_e2e.py`): Real images
+   - Full workflow: create project, add layers, apply filters, export
+   - Format conversion (PNG->JPEG, etc.)
+   - Blend mode compositing verification
+   - Filter effect pixel-level verification
+   - Multi-layer compositing
+   - Text rendering
+   - CLI subprocess invocation

package/python/agent-harness/build/lib/cli_anything/gimp/__init__.py

@@ -0,0 +1 @@
+"""GIMP CLI - A stateful CLI for image editing."""

package/python/agent-harness/build/lib/cli_anything/gimp/__main__.py

@@ -0,0 +1,3 @@
+"""Allow running as python3 -m cli.gimp_cli"""
+from cli_anything.gimp.gimp_cli import main
+main()

package/python/agent-harness/build/lib/cli_anything/gimp/core/__init__.py

@@ -0,0 +1 @@
+"""GIMP CLI - Core modules."""

package/python/agent-harness/build/lib/cli_anything/gimp/core/canvas.py

@@ -0,0 +1,193 @@
+"""GIMP CLI - Canvas operations module."""
+
+from typing import Dict, Any
+
+
+VALID_MODES = ("RGB", "RGBA", "L", "LA", "CMYK", "P")
+RESAMPLE_METHODS = ("nearest", "bilinear", "bicubic", "lanczos")
+
+
+def resize_canvas(
+    project: Dict[str, Any],
+    width: int,
+    height: int,
+    anchor: str = "center",
+) -> Dict[str, Any]:
+    """Resize the canvas (does not scale content, adds/removes space).
+
+    Args:
+        project: The project dict
+        width: New canvas width
+        height: New canvas height
+        anchor: Where to anchor existing content:
+                "center", "top-left", "top-right", "bottom-left", "bottom-right",
+                "top", "bottom", "left", "right"
+    """
+    if width < 1 or height < 1:
+        raise ValueError(f"Canvas dimensions must be positive: {width}x{height}")
+
+    valid_anchors = [
+        "center", "top-left", "top-right", "bottom-left", "bottom-right",
+        "top", "bottom", "left", "right",
+    ]
+    if anchor not in valid_anchors:
+        raise ValueError(f"Invalid anchor: {anchor}. Valid: {valid_anchors}")
+
+    old_w = project["canvas"]["width"]
+    old_h = project["canvas"]["height"]
+
+    # Calculate offset for existing layers based on anchor
+    dx, dy = _anchor_offset(old_w, old_h, width, height, anchor)
+
+    project["canvas"]["width"] = width
+    project["canvas"]["height"] = height
+
+    # Adjust layer offsets
+    for layer in project.get("layers", []):
+        layer["offset_x"] = layer.get("offset_x", 0) + dx
+        layer["offset_y"] = layer.get("offset_y", 0) + dy
+
+    return {
+        "old_size": f"{old_w}x{old_h}",
+        "new_size": f"{width}x{height}",
+        "anchor": anchor,
+        "offset_applied": f"({dx}, {dy})",
+    }
+
+
+def scale_canvas(
+    project: Dict[str, Any],
+    width: int,
+    height: int,
+    resample: str = "lanczos",
+) -> Dict[str, Any]:
+    """Scale the canvas and all layers proportionally.
+
+    This marks layers for rescaling at render time.
+    """
+    if width < 1 or height < 1:
+        raise ValueError(f"Canvas dimensions must be positive: {width}x{height}")
+    if resample not in RESAMPLE_METHODS:
+        raise ValueError(f"Invalid resample method: {resample}. Valid: {list(RESAMPLE_METHODS)}")
+
+    old_w = project["canvas"]["width"]
+    old_h = project["canvas"]["height"]
+    scale_x = width / old_w
+    scale_y = height / old_h
+
+    project["canvas"]["width"] = width
+    project["canvas"]["height"] = height
+
+    # Mark layers for proportional scaling
+    for layer in project.get("layers", []):
+        layer["_scale_x"] = scale_x
+        layer["_scale_y"] = scale_y
+        layer["_resample"] = resample
+        layer["offset_x"] = round(layer.get("offset_x", 0) * scale_x)
+        layer["offset_y"] = round(layer.get("offset_y", 0) * scale_y)
+        if "width" in layer:
+            layer["width"] = round(layer["width"] * scale_x)
+        if "height" in layer:
+            layer["height"] = round(layer["height"] * scale_y)
+
+    return {
+        "old_size": f"{old_w}x{old_h}",
+        "new_size": f"{width}x{height}",
+        "scale": f"({scale_x:.3f}, {scale_y:.3f})",
+        "resample": resample,
+    }
+
+
+def crop_canvas(
+    project: Dict[str, Any],
+    left: int,
+    top: int,
+    right: int,
+    bottom: int,
+) -> Dict[str, Any]:
+    """Crop the canvas to a rectangle."""
+    if left < 0 or top < 0:
+        raise ValueError(f"Crop coordinates must be non-negative: left={left}, top={top}")
+    if right <= left or bottom <= top:
+        raise ValueError(f"Invalid crop region: ({left},{top})-({right},{bottom})")
+
+    old_w = project["canvas"]["width"]
+    old_h = project["canvas"]["height"]
+
+    if right > old_w or bottom > old_h:
+        raise ValueError(
+            f"Crop region ({left},{top})-({right},{bottom}) exceeds canvas {old_w}x{old_h}"
+        )
+
+    new_w = right - left
+    new_h = bottom - top
+
+    project["canvas"]["width"] = new_w
+    project["canvas"]["height"] = new_h
+
+    # Adjust layer offsets
+    for layer in project.get("layers", []):
+        layer["offset_x"] = layer.get("offset_x", 0) - left
+        layer["offset_y"] = layer.get("offset_y", 0) - top
+
+    return {
+        "old_size": f"{old_w}x{old_h}",
+        "new_size": f"{new_w}x{new_h}",
+        "crop_region": f"({left},{top})-({right},{bottom})",
+    }
+
+
+def set_mode(project: Dict[str, Any], mode: str) -> Dict[str, Any]:
+    """Set the canvas color mode."""
+    mode = mode.upper()
+    if mode not in VALID_MODES:
+        raise ValueError(f"Invalid color mode: {mode}. Valid: {list(VALID_MODES)}")
+    old_mode = project["canvas"].get("color_mode", "RGB")
+    project["canvas"]["color_mode"] = mode
+    return {"old_mode": old_mode, "new_mode": mode}
+
+
+def set_dpi(project: Dict[str, Any], dpi: int) -> Dict[str, Any]:
+    """Set the canvas DPI (dots per inch)."""
+    if dpi < 1:
+        raise ValueError(f"DPI must be positive: {dpi}")
+    old_dpi = project["canvas"].get("dpi", 72)
+    project["canvas"]["dpi"] = dpi
+    return {"old_dpi": old_dpi, "new_dpi": dpi}
+
+
+def get_canvas_info(project: Dict[str, Any]) -> Dict[str, Any]:
+    """Get canvas information."""
+    c = project["canvas"]
+    w, h = c["width"], c["height"]
+    dpi = c.get("dpi", 72)
+    return {
+        "width": w,
+        "height": h,
+        "color_mode": c.get("color_mode", "RGB"),
+        "background": c.get("background", "#ffffff"),
+        "dpi": dpi,
+        "size_inches": f"{w/dpi:.2f} x {h/dpi:.2f}",
+        "megapixels": f"{w * h / 1_000_000:.2f} MP",
+    }
+
+
+def _anchor_offset(
+    old_w: int, old_h: int, new_w: int, new_h: int, anchor: str
+) -> tuple:
+    """Calculate pixel offset for content based on anchor position."""
+    dx_map = {
+        "top-left": 0, "left": 0, "bottom-left": 0,
+        "top": (new_w - old_w) // 2, "center": (new_w - old_w) // 2,
+        "bottom": (new_w - old_w) // 2,
+        "top-right": new_w - old_w, "right": new_w - old_w,
+        "bottom-right": new_w - old_w,
+    }
+    dy_map = {
+        "top-left": 0, "top": 0, "top-right": 0,
+        "left": (new_h - old_h) // 2, "center": (new_h - old_h) // 2,
+        "right": (new_h - old_h) // 2,
+        "bottom-left": new_h - old_h, "bottom": new_h - old_h,
+        "bottom-right": new_h - old_h,
+    }
+    return dx_map.get(anchor, 0), dy_map.get(anchor, 0)