discoclaw 0.2.4 → 0.3.0

package/dist/runtime/tools/fs-glob.test.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { execute, name, schema, simpleGlobMatch } from './fs-glob.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-glob-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('fs-glob schema', () => {
+    it('has correct name and shape', () => {
+        expect(name).toBe('list_files');
+        expect(schema.type).toBe('function');
+        expect(schema.function.name).toBe('list_files');
+        expect(schema.function.parameters).toHaveProperty('required', ['pattern']);
+    });
+});
+describe('simpleGlobMatch', () => {
+    it('matches *.ts against .ts files', () => {
+        expect(simpleGlobMatch('foo.ts', '*.ts')).toBe(true);
+        expect(simpleGlobMatch('foo.js', '*.ts')).toBe(false);
+    });
+    it('matches **/*.ts recursively', () => {
+        expect(simpleGlobMatch('src/foo.ts', '**/*.ts')).toBe(true);
+        expect(simpleGlobMatch('src/deep/bar.ts', '**/*.ts')).toBe(true);
+        expect(simpleGlobMatch('foo.js', '**/*.ts')).toBe(false);
+    });
+    it('matches ** alone for any path', () => {
+        expect(simpleGlobMatch('foo.ts', '**')).toBe(true);
+        expect(simpleGlobMatch('src/foo.ts', '**')).toBe(true);
+    });
+    it('matches ? as a single character', () => {
+        expect(simpleGlobMatch('a.ts', '?.ts')).toBe(true);
+        expect(simpleGlobMatch('ab.ts', '?.ts')).toBe(false);
+    });
+});
+describe('fs-glob execute', () => {
+    it('finds files matching a glob pattern', async () => {
+        await fs.writeFile(path.join(tmpDir, 'a.ts'), '');
+        await fs.writeFile(path.join(tmpDir, 'b.ts'), '');
+        await fs.writeFile(path.join(tmpDir, 'c.js'), '');
+        const r = await execute({ pattern: '*.ts', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('a.ts');
+        expect(r.result).toContain('b.ts');
+        expect(r.result).not.toContain('c.js');
+    });
+    it('returns message when no files match', async () => {
+        const r = await execute({ pattern: '*.xyz', path: tmpDir }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('No files matched');
+    });
+    it('returns error when pattern is missing', async () => {
+        const r = await execute({}, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('pattern');
+    });
+    it('uses first allowed root as default search path', async () => {
+        await fs.writeFile(path.join(tmpDir, 'file.txt'), '');
+        const r = await execute({ pattern: '*.txt' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toContain('file.txt');
+    });
+});

package/dist/runtime/tools/fs-read-file.js

@@ -0,0 +1,49 @@
+/**
+ * OpenAI function-calling tool: read_file
+ *
+ * Reads the contents of a file at a given path, with optional line
+ * offset and limit for partial reads. Enforces a 1 MB size cap.
+ */
+import fs from 'node:fs/promises';
+import { resolveAndCheck } from './path-security.js';
+export const name = 'read_file';
+const MAX_READ_BYTES = 1 * 1024 * 1024; // 1 MB
+export const schema = {
+    type: 'function',
+    function: {
+        name: 'read_file',
+        description: 'Read the contents of a file at the given path.',
+        parameters: {
+            type: 'object',
+            properties: {
+                file_path: { type: 'string', description: 'Absolute path to the file to read.' },
+                offset: { type: 'number', description: 'Line number to start reading from (1-based).' },
+                limit: { type: 'number', description: 'Maximum number of lines to read.' },
+            },
+            required: ['file_path'],
+            additionalProperties: false,
+        },
+    },
+};
+export async function execute(args, allowedRoots) {
+    const filePath = args.file_path;
+    if (!filePath)
+        return { result: 'file_path is required', ok: false };
+    try {
+        const resolved = await resolveAndCheck(filePath, allowedRoots);
+        const stat = await fs.stat(resolved);
+        if (stat.size > MAX_READ_BYTES) {
+            return { result: `File too large: ${stat.size} bytes (max ${MAX_READ_BYTES})`, ok: false };
+        }
+        const content = await fs.readFile(resolved, 'utf-8');
+        const lines = content.split('\n');
+        const offset = typeof args.offset === 'number' ? Math.max(0, args.offset - 1) : 0; // 1-based to 0-based
+        const limit = typeof args.limit === 'number' ? args.limit : lines.length;
+        const sliced = lines.slice(offset, offset + limit);
+        return { result: sliced.join('\n'), ok: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { result: message, ok: false };
+    }
+}

package/dist/runtime/tools/fs-read-file.test.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { execute, name, schema } from './fs-read-file.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-read-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('fs-read-file schema', () => {
+    it('has correct name and shape', () => {
+        expect(name).toBe('read_file');
+        expect(schema.type).toBe('function');
+        expect(schema.function.name).toBe('read_file');
+        expect(schema.function.parameters).toHaveProperty('required', ['file_path']);
+    });
+});
+describe('fs-read-file execute', () => {
+    it('reads an existing file', async () => {
+        const filePath = path.join(tmpDir, 'hello.txt');
+        await fs.writeFile(filePath, 'hello world\n');
+        const r = await execute({ file_path: filePath }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('hello world\n');
+    });
+    it('returns error for nonexistent file', async () => {
+        const r = await execute({ file_path: path.join(tmpDir, 'nope.txt') }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/ENOENT|no such file|not accessible/i);
+    });
+    it('reads with offset and limit', async () => {
+        const filePath = path.join(tmpDir, 'lines.txt');
+        await fs.writeFile(filePath, 'line1\nline2\nline3\nline4\nline5\n');
+        const r = await execute({ file_path: filePath, offset: 2, limit: 2 }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe('line2\nline3');
+    });
+    it('returns error when file_path is missing', async () => {
+        const r = await execute({}, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('file_path');
+    });
+    it('rejects path outside allowed roots', async () => {
+        const r = await execute({ file_path: '/etc/hostname' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+    });
+});

package/dist/runtime/tools/fs-realpath.js

@@ -0,0 +1,51 @@
+/**
+ * OpenAI function-calling tool: realpath
+ *
+ * Resolves a file or directory path to its canonical absolute path,
+ * following all symlinks. Returns an error if the path does not exist
+ * or falls outside the allowed roots.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { canonicalizeRoots } from './path-security.js';
+export const name = 'realpath';
+export const schema = {
+    type: 'function',
+    function: {
+        name: 'realpath',
+        description: 'Resolve the canonical absolute path of a file or directory, following symlinks.',
+        parameters: {
+            type: 'object',
+            properties: {
+                file_path: { type: 'string', description: 'Path to resolve (absolute or relative to workspace).' },
+            },
+            required: ['file_path'],
+            additionalProperties: false,
+        },
+    },
+};
+export async function execute(args, allowedRoots) {
+    const filePath = args.file_path;
+    if (!filePath)
+        return { result: 'file_path is required', ok: false };
+    // Resolve relative paths against the first allowed root
+    const resolved = path.resolve(allowedRoots[0], filePath);
+    let canonical;
+    try {
+        canonical = await fs.realpath(resolved);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT') {
+            return { result: `Path does not exist: ${resolved}`, ok: false };
+        }
+        return { result: `Cannot resolve path: ${resolved}`, ok: false };
+    }
+    // Verify the canonical path falls within allowed roots
+    const canonicalRoots = await canonicalizeRoots(allowedRoots);
+    const allowed = canonicalRoots.some((root) => canonical === root || canonical.startsWith(root + path.sep));
+    if (!allowed) {
+        return { result: `Path outside allowed roots: ${filePath}`, ok: false };
+    }
+    return { result: canonical, ok: true };
+}

package/dist/runtime/tools/fs-realpath.test.js

@@ -0,0 +1,72 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { execute, name, schema } from './fs-realpath.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-realpath-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('fs-realpath schema', () => {
+    it('has correct name and shape', () => {
+        expect(name).toBe('realpath');
+        expect(schema.type).toBe('function');
+        expect(schema.function.name).toBe('realpath');
+        expect(schema.function.parameters).toHaveProperty('required', ['file_path']);
+    });
+});
+describe('fs-realpath execute', () => {
+    it('resolves an existing file to its canonical path', async () => {
+        const filePath = path.join(tmpDir, 'hello.txt');
+        await fs.writeFile(filePath, 'hello');
+        const r = await execute({ file_path: filePath }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        // The result should be the canonical path
+        const expected = await fs.realpath(filePath);
+        expect(r.result).toBe(expected);
+    });
+    it('resolves a symlink to its target', async () => {
+        const target = path.join(tmpDir, 'target.txt');
+        await fs.writeFile(target, 'content');
+        const link = path.join(tmpDir, 'link.txt');
+        await fs.symlink(target, link);
+        const r = await execute({ file_path: link }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe(await fs.realpath(target));
+    });
+    it('resolves a relative path against the first allowed root', async () => {
+        await fs.writeFile(path.join(tmpDir, 'rel.txt'), 'data');
+        const r = await execute({ file_path: 'rel.txt' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        expect(r.result).toBe(await fs.realpath(path.join(tmpDir, 'rel.txt')));
+    });
+    it('returns error for nonexistent path', async () => {
+        const r = await execute({ file_path: path.join(tmpDir, 'nope.txt') }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('does not exist');
+    });
+    it('returns error when file_path is missing', async () => {
+        const r = await execute({}, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('file_path');
+    });
+    it('rejects symlink pointing outside allowed roots', async () => {
+        const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-outside-'));
+        const outsideFile = path.join(outsideDir, 'secret.txt');
+        await fs.writeFile(outsideFile, 'secret');
+        const link = path.join(tmpDir, 'escape');
+        await fs.symlink(outsideFile, link);
+        const r = await execute({ file_path: link }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('outside allowed roots');
+        await fs.rm(outsideDir, { recursive: true, force: true });
+    });
+    it('rejects absolute path outside allowed roots', async () => {
+        const r = await execute({ file_path: '/etc/hostname' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|does not exist/i);
+    });
+});

package/dist/runtime/tools/fs-write-file.js

@@ -0,0 +1,45 @@
+/**
+ * OpenAI function-calling tool: write_file
+ *
+ * Writes content to a file, creating parent directories as needed.
+ * Overwrites the file if it already exists.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { resolveAndCheck } from './path-security.js';
+export const name = 'write_file';
+export const schema = {
+    type: 'function',
+    function: {
+        name: 'write_file',
+        description: 'Write content to a file, creating or overwriting it.',
+        parameters: {
+            type: 'object',
+            properties: {
+                file_path: { type: 'string', description: 'Absolute path to the file to write.' },
+                content: { type: 'string', description: 'The full content to write to the file.' },
+            },
+            required: ['file_path', 'content'],
+            additionalProperties: false,
+        },
+    },
+};
+export async function execute(args, allowedRoots) {
+    const filePath = args.file_path;
+    const content = args.content;
+    if (!filePath)
+        return { result: 'file_path is required', ok: false };
+    if (typeof content !== 'string')
+        return { result: 'content is required', ok: false };
+    try {
+        const resolved = await resolveAndCheck(filePath, allowedRoots, true);
+        // Ensure parent directory exists
+        await fs.mkdir(path.dirname(resolved), { recursive: true });
+        await fs.writeFile(resolved, content, 'utf-8');
+        return { result: `Wrote ${Buffer.byteLength(content)} bytes to ${resolved}`, ok: true };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { result: message, ok: false };
+    }
+}

package/dist/runtime/tools/fs-write-file.test.js

@@ -0,0 +1,56 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { execute, name, schema } from './fs-write-file.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-write-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+describe('fs-write-file schema', () => {
+    it('has correct name and shape', () => {
+        expect(name).toBe('write_file');
+        expect(schema.type).toBe('function');
+        expect(schema.function.name).toBe('write_file');
+        expect(schema.function.parameters).toHaveProperty('required', ['file_path', 'content']);
+    });
+});
+describe('fs-write-file execute', () => {
+    it('writes a new file and creates parent directories', async () => {
+        const filePath = path.join(tmpDir, 'sub', 'dir', 'output.txt');
+        const r = await execute({ file_path: filePath, content: 'created!' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const contents = await fs.readFile(filePath, 'utf-8');
+        expect(contents).toBe('created!');
+    });
+    it('overwrites an existing file', async () => {
+        const filePath = path.join(tmpDir, 'existing.txt');
+        await fs.writeFile(filePath, 'old content');
+        const r = await execute({ file_path: filePath, content: 'new content' }, [tmpDir]);
+        expect(r.ok).toBe(true);
+        const contents = await fs.readFile(filePath, 'utf-8');
+        expect(contents).toBe('new content');
+    });
+    it('returns error when content is missing', async () => {
+        const r = await execute({ file_path: path.join(tmpDir, 'x.txt') }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('content');
+    });
+    it('returns error when file_path is missing', async () => {
+        const r = await execute({ content: 'data' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('file_path');
+    });
+    it('rejects write outside allowed roots', async () => {
+        const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'discoclaw-outside-'));
+        const filePath = path.join(outsideDir, 'injected.txt');
+        const r = await execute({ file_path: filePath, content: 'injected' }, [tmpDir]);
+        expect(r.ok).toBe(false);
+        expect(r.result).toMatch(/outside allowed roots|not accessible/i);
+        await expect(fs.access(filePath)).rejects.toThrow();
+        await fs.rm(outsideDir, { recursive: true, force: true });
+    });
+});

package/dist/runtime/tools/image-download.js

@@ -0,0 +1,138 @@
+/**
+ * OpenAI function-calling tool: download_image
+ *
+ * Downloads an image from a URL and returns it as base64-encoded data.
+ * Includes SSRF protections, size limits, and magic-byte validation.
+ */
+export const name = 'download_image';
+const FETCH_TIMEOUT_MS = 15_000;
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024; // 20 MB
+/** RFC 1918 / private / loopback prefixes for SSRF protection. */
+const PRIVATE_IP_PREFIXES = [
+    '10.',
+    '172.16.', '172.17.', '172.18.', '172.19.',
+    '172.20.', '172.21.', '172.22.', '172.23.',
+    '172.24.', '172.25.', '172.26.', '172.27.',
+    '172.28.', '172.29.', '172.30.', '172.31.',
+    '192.168.',
+    '127.',
+    '0.',
+    '169.254.',
+];
+const LOCALHOST_HOSTNAMES = new Set(['localhost', '[::1]']);
+const SUPPORTED_MEDIA_TYPES = new Set([
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+]);
+export const schema = {
+    type: 'function',
+    function: {
+        name: 'download_image',
+        description: 'Download an image from a URL and return it as base64-encoded data with its media type.',
+        parameters: {
+            type: 'object',
+            properties: {
+                url: { type: 'string', description: 'The HTTPS URL of the image to download.' },
+            },
+            required: ['url'],
+            additionalProperties: false,
+        },
+    },
+};
+/**
+ * Sniff the image format from magic bytes.
+ * Returns the MIME type string or null if unrecognized.
+ */
+export function sniffMediaType(buffer) {
+    // PNG: 8-byte signature 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.length >= 8 &&
+        buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4E && buffer[3] === 0x47 &&
+        buffer[4] === 0x0D && buffer[5] === 0x0A && buffer[6] === 0x1A && buffer[7] === 0x0A) {
+        return 'image/png';
+    }
+    // JPEG: 3-byte SOI + marker FF D8 FF
+    if (buffer.length >= 3 &&
+        buffer[0] === 0xFF && buffer[1] === 0xD8 && buffer[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    // GIF: 6-byte version string GIF87a or GIF89a
+    if (buffer.length >= 6 &&
+        buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38 &&
+        (buffer[4] === 0x37 || buffer[4] === 0x39) && buffer[5] === 0x61) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP (bytes 0-3 = RIFF, bytes 8-11 = WEBP)
+    if (buffer.length >= 12 &&
+        buffer[0] === 0x52 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x46 &&
+        buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    return null;
+}
+export async function execute(args, _allowedRoots) {
+    const url = args.url;
+    if (!url)
+        return { result: 'url is required', ok: false };
+    // Validate URL
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { result: 'Invalid URL', ok: false };
+    }
+    // HTTPS only
+    if (parsed.protocol !== 'https:') {
+        return { result: `Blocked: only HTTPS URLs are allowed (got ${parsed.protocol})`, ok: false };
+    }
+    // Block private/loopback IPs and localhost
+    const hostname = parsed.hostname;
+    if (LOCALHOST_HOSTNAMES.has(hostname)) {
+        return { result: 'Blocked: localhost URLs are not allowed', ok: false };
+    }
+    if (PRIVATE_IP_PREFIXES.some((prefix) => hostname.startsWith(prefix))) {
+        return { result: 'Blocked: private/internal IP addresses are not allowed', ok: false };
+    }
+    if (hostname === '::1' || hostname === '[::1]') {
+        return { result: 'Blocked: loopback addresses are not allowed', ok: false };
+    }
+    try {
+        const response = await fetch(url, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            redirect: 'error',
+        });
+        if (!response.ok) {
+            return { result: `HTTP ${response.status} ${response.statusText}`, ok: false };
+        }
+        const buffer = Buffer.from(await response.arrayBuffer());
+        if (buffer.length > MAX_IMAGE_BYTES) {
+            const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
+            return { result: `Image too large: ${sizeMB} MB (max 20 MB)`, ok: false };
+        }
+        // Validate image format via magic bytes
+        const mediaType = sniffMediaType(buffer);
+        if (!mediaType) {
+            return { result: 'Not a recognized image format (expected PNG, JPEG, GIF, or WebP)', ok: false };
+        }
+        if (!SUPPORTED_MEDIA_TYPES.has(mediaType)) {
+            return { result: `Unsupported image format: ${mediaType}`, ok: false };
+        }
+        const base64 = buffer.toString('base64');
+        return {
+            result: JSON.stringify({ base64, media_type: mediaType, size: buffer.length }),
+            ok: true,
+        };
+    }
+    catch (err) {
+        const e = err instanceof Error ? err : null;
+        if (e?.name === 'TimeoutError' || e?.name === 'AbortError') {
+            return { result: 'Request timed out (15s limit)', ok: false };
+        }
+        if (e?.name === 'TypeError' && String(e.message).includes('redirect')) {
+            return { result: 'Blocked: unexpected redirect', ok: false };
+        }
+        return { result: e?.message || 'download failed', ok: false };
+    }
+}

package/dist/runtime/tools/image-download.test.js

@@ -0,0 +1,106 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { execute, name, schema, sniffMediaType } from './image-download.js';
+// Minimal valid PNG: 8-byte signature
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]);
+// Minimal valid JPEG: SOI + marker
+const JPEG_HEADER = Buffer.from([0xFF, 0xD8, 0xFF, 0xE0]);
+// Minimal valid GIF: GIF89a
+const GIF_HEADER = Buffer.from([0x47, 0x49, 0x46, 0x38, 0x39, 0x61]);
+// Minimal valid WebP: RIFF....WEBP
+const WEBP_HEADER = Buffer.from([
+    0x52, 0x49, 0x46, 0x46, // RIFF
+    0x00, 0x00, 0x00, 0x00, // file size (placeholder)
+    0x57, 0x45, 0x42, 0x50, // WEBP
+]);
+describe('image-download schema', () => {
+    it('has correct name and shape', () => {
+        expect(name).toBe('download_image');
+        expect(schema.type).toBe('function');
+        expect(schema.function.name).toBe('download_image');
+        expect(schema.function.parameters).toHaveProperty('required', ['url']);
+    });
+});
+describe('sniffMediaType', () => {
+    it('detects PNG', () => {
+        expect(sniffMediaType(PNG_HEADER)).toBe('image/png');
+    });
+    it('detects JPEG', () => {
+        expect(sniffMediaType(JPEG_HEADER)).toBe('image/jpeg');
+    });
+    it('detects GIF', () => {
+        expect(sniffMediaType(GIF_HEADER)).toBe('image/gif');
+    });
+    it('detects WebP', () => {
+        expect(sniffMediaType(WEBP_HEADER)).toBe('image/webp');
+    });
+    it('returns null for unknown formats', () => {
+        expect(sniffMediaType(Buffer.from([0x00, 0x00, 0x00, 0x00]))).toBeNull();
+    });
+    it('returns null for empty buffer', () => {
+        expect(sniffMediaType(Buffer.alloc(0))).toBeNull();
+    });
+});
+describe('image-download execute', () => {
+    const originalFetch = globalThis.fetch;
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+    it('downloads and returns a PNG image as base64', async () => {
+        // Create a minimal valid PNG (header + some padding)
+        const pngData = Buffer.concat([PNG_HEADER, Buffer.alloc(100)]);
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response(pngData, { status: 200 }));
+        const r = await execute({ url: 'https://example.com/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(true);
+        const parsed = JSON.parse(r.result);
+        expect(parsed.media_type).toBe('image/png');
+        expect(parsed.base64).toBe(pngData.toString('base64'));
+        expect(parsed.size).toBe(pngData.length);
+    });
+    it('returns error when url is missing', async () => {
+        const r = await execute({}, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('url');
+    });
+    it('rejects HTTP (non-HTTPS) URLs', async () => {
+        const r = await execute({ url: 'http://example.com/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('HTTPS');
+    });
+    it('rejects private IP addresses', async () => {
+        const r = await execute({ url: 'https://10.0.0.1/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+    it('rejects localhost', async () => {
+        const r = await execute({ url: 'https://localhost/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('localhost');
+    });
+    it('rejects 192.168.x addresses', async () => {
+        const r = await execute({ url: 'https://192.168.1.1/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+    it('rejects loopback IP (127.x)', async () => {
+        const r = await execute({ url: 'https://127.0.0.1/image.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('private');
+    });
+    it('rejects invalid URLs', async () => {
+        const r = await execute({ url: 'not-a-url' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('Invalid URL');
+    });
+    it('returns error for non-image content', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response('plain text', { status: 200 }));
+        const r = await execute({ url: 'https://example.com/file.txt' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('Not a recognized image format');
+    });
+    it('returns error on HTTP error status', async () => {
+        globalThis.fetch = vi.fn().mockResolvedValue(new Response('not found', { status: 404, statusText: 'Not Found' }));
+        const r = await execute({ url: 'https://example.com/missing.png' }, ['/tmp']);
+        expect(r.ok).toBe(false);
+        expect(r.result).toContain('404');
+    });
+});