autoclaw 1.3.4 → 1.3.6

package/dist/skills.js

@@ -0,0 +1,276 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { createZip, readZip } from './zip.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Built-in skills ship with the package (dist/../skills); user + project
+// scopes shadow built-ins on name collisions (project > user > builtin).
+export function builtinSkillsDir() {
+    return path.resolve(__dirname, '..', 'skills');
+}
+export function defaultSkillScopes() {
+    return [
+        { dir: builtinSkillsDir(), source: 'builtin' },
+        { dir: path.join(os.homedir(), '.autoclaw', 'skills'), source: 'user' },
+        { dir: path.resolve(process.cwd(), '.autoclaw', 'skills'), source: 'project' },
+    ];
+}
+export function parseSkillMd(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return null;
+    const frontmatter = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        const kv = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!kv)
+            continue;
+        let value = kv[2].trim();
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        frontmatter[kv[1]] = value;
+    }
+    return { frontmatter, body: raw.slice(match[0].length) };
+}
+function toMeta(frontmatter, dir, source) {
+    const bool = (v) => v === 'true' ? true : v === 'false' ? false : undefined;
+    return {
+        name: frontmatter.name || path.basename(dir),
+        displayName: frontmatter.display_name,
+        description: frontmatter.description || frontmatter.description_zh || frontmatter.description_en || '',
+        descriptionZh: frontmatter.description_zh,
+        descriptionEn: frontmatter.description_en,
+        version: frontmatter.version,
+        author: frontmatter.author,
+        category: frontmatter.category,
+        disableModelInvocation: bool(frontmatter['disable-model-invocation']),
+        userInvocable: bool(frontmatter['user-invocable']),
+        source,
+        dir,
+        skillMdPath: path.join(dir, 'SKILL.md'),
+    };
+}
+// Later scopes win on name collisions. Dirs starting with '.' are skipped.
+export function discoverSkills(scopes) {
+    const warnings = [];
+    const byName = new Map();
+    for (const scope of scopes) {
+        let entries = [];
+        try {
+            entries = fs.readdirSync(scope.dir, { withFileTypes: true })
+                .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+                .map(e => e.name);
+        }
+        catch { /* scope dir missing — fine */
+            continue;
+        }
+        for (const entry of entries) {
+            const dir = path.join(scope.dir, entry);
+            const skillMdPath = path.join(dir, 'SKILL.md');
+            let raw;
+            try {
+                raw = fs.readFileSync(skillMdPath, 'utf-8');
+            }
+            catch {
+                warnings.push(`skipped ${dir}: no SKILL.md`);
+                continue;
+            }
+            try {
+                const parsed = parseSkillMd(raw);
+                if (!parsed) {
+                    warnings.push(`skipped ${skillMdPath}: missing YAML frontmatter`);
+                    continue;
+                }
+                const meta = toMeta(parsed.frontmatter, dir, scope.source);
+                if (!meta.description) {
+                    warnings.push(`skipped ${skillMdPath}: empty description`);
+                    continue;
+                }
+                byName.set(meta.name, meta);
+            }
+            catch (err) {
+                warnings.push(`skipped ${skillMdPath}: ${err?.message || err}`);
+            }
+        }
+    }
+    return { skills: [...byName.values()], warnings };
+}
+// ---- system-prompt manifest (progressive disclosure: one line per skill) ----
+function truncate(text, max) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? flat.slice(0, max - 1) + '…' : flat;
+}
+export function buildSkillsManifest(config, scopes) {
+    if (config?.skillsEnabled === false)
+        return null;
+    const { skills } = discoverSkills(scopes || defaultSkillScopes());
+    const visible = skills.filter(s => s.disableModelInvocation !== true);
+    if (visible.length === 0)
+        return null;
+    const lines = visible.map(s => `- ${s.name}${s.version ? ` (v${s.version})` : ''}: ${truncate(s.description, 160)} [read ${s.skillMdPath}]`);
+    return [
+        'INSTALLED SKILL PACKAGES (procedural capabilities bundling instructions, scripts and templates).',
+        'When a task matches a skill, first read its SKILL.md and follow it — skills run through your normal file and shell tools, no special API:',
+        ...lines,
+    ].join('\n');
+}
+// ---- install / remove ----
+const INSTALL_SKIP = new Set(['node_modules', '.git', '__MACOSX']);
+function isJunkPath(rel) {
+    return rel.split('/').some(s => INSTALL_SKIP.has(s)) || rel.split('/').pop() === '.DS_Store';
+}
+// Skill directory names come from untrusted frontmatter, so restrict to
+// letters (any script, e.g. Chinese), digits, dot, underscore, dash — no
+// separators, no leading dot (discovery skips dot-dirs), bounded length.
+function isSafeSkillName(name) {
+    return name.length <= 64 && /^[\p{L}\p{N}][\p{L}\p{N}._-]*$/u.test(name);
+}
+function copyTree(src, dest) {
+    let count = 0;
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (INSTALL_SKIP.has(entry.name) || entry.name === '.DS_Store')
+            continue;
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory())
+            count += copyTree(s, d);
+        else if (entry.isFile()) {
+            fs.copyFileSync(s, d);
+            count++;
+        }
+    }
+    return count;
+}
+export function userSkillsDir() {
+    return path.join(os.homedir(), '.autoclaw', 'skills');
+}
+// Install from a skill directory, a zip package, or an https URL into the
+// user scope (~/.autoclaw/skills/). The installed directory is named after
+// the skill's frontmatter `name` (fallback: the folder/zip stem), so the
+// path always matches what discovery and the manifest expect.
+export function installSkill(target, opts) {
+    const userDir = opts?.userDir || userSkillsDir();
+    const stat = fs.existsSync(target) ? fs.statSync(target) : null;
+    if (!stat)
+        throw new Error(`target not found: ${target}`);
+    if (stat.isDirectory()) {
+        const skillMdPath = path.join(target, 'SKILL.md');
+        if (!fs.existsSync(skillMdPath))
+            throw new Error(`${target} is not a skill (no SKILL.md)`);
+        const parsed = parseSkillMd(fs.readFileSync(skillMdPath, 'utf-8'));
+        const name = pickSafeName(parsed?.frontmatter.name, path.basename(path.resolve(target)));
+        const dest = path.join(userDir, name);
+        const files = copyTree(target, dest);
+        return { name, dir: dest, files };
+    }
+    // zip package: locate the SKILL.md entry, rebase its dir to userDir/<name>.
+    // Works with third-party layouts: SKILL.md at the zip root, a plain folder,
+    // or a skills/<name>/ wrapper, independently of frontmatter-vs-folder naming.
+    const buf = fs.readFileSync(target);
+    const entries = readZip(buf).map(e => ({ ...e, path: e.path.replace(/\\/g, '/') }));
+    const candidates = entries
+        .filter(e => /(^|\/)SKILL\.md$/.test(e.path))
+        .sort((a, b) => a.path.split('/').length - b.path.split('/').length);
+    if (candidates.length === 0)
+        throw new Error('zip contains no SKILL.md — not a skill package');
+    const pick = candidates[0];
+    const rootDir = pick.path.split('/').slice(0, -1).join('/');
+    const parsed = parseSkillMd(pick.data.toString('utf-8'));
+    const fallback = rootDir ? rootDir.split('/').filter(Boolean).pop() : path.basename(target).replace(/\.zip$/i, '');
+    const name = pickSafeName(parsed?.frontmatter.name, fallback);
+    const prefix = rootDir ? rootDir + '/' : '';
+    const dest = path.join(userDir, name);
+    const destResolved = path.resolve(dest) + path.sep;
+    const wanted = entries
+        .filter(e => prefix ? e.path.startsWith(prefix) : true)
+        .map(e => ({ rel: prefix ? e.path.slice(prefix.length) : e.path, data: e.data }))
+        .filter(e => e.rel !== '' && !e.rel.endsWith('/') && !isJunkPath(e.rel));
+    // Validate every target path before writing anything: a hostile entry must
+    // reject the whole archive, not half-install it.
+    const targets = wanted.map(e => {
+        const destFile = path.resolve(dest, ...e.rel.split('/'));
+        if (!destFile.startsWith(destResolved))
+            throw new Error(`unsafe zip entry: ${e.rel}`);
+        return { destFile, data: e.data };
+    });
+    for (const t of targets) {
+        fs.mkdirSync(path.dirname(t.destFile), { recursive: true });
+        fs.writeFileSync(t.destFile, t.data);
+    }
+    return { name, dir: dest, files: targets.length };
+}
+function pickSafeName(primary, fallback) {
+    const candidate = primary && isSafeSkillName(primary) ? primary : fallback;
+    if (!isSafeSkillName(candidate)) {
+        throw new Error(`unsafe skill name: ${JSON.stringify(primary || fallback)}`);
+    }
+    return candidate;
+}
+// Download an https zip package to a temp file and install it.
+export async function installSkillFromUrl(url, opts) {
+    if (!/^https:\/\//.test(url))
+        throw new Error('only https URLs are supported');
+    const res = await fetch(url, { signal: AbortSignal.timeout(120000) });
+    if (!res.ok)
+        throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length > 100 * 1024 * 1024)
+        throw new Error('skill package exceeds 100 MB limit');
+    const tmp = path.join(os.tmpdir(), `autoclaw-skill-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`);
+    fs.writeFileSync(tmp, buf);
+    try {
+        return installSkill(tmp, opts);
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+}
+export function removeSkill(name, opts) {
+    const scopes = opts?.scopes || defaultSkillScopes();
+    const { skills } = discoverSkills(scopes);
+    const skill = skills.find(s => s.name === name);
+    if (!skill)
+        return 'not-found';
+    if (skill.source === 'builtin')
+        return 'builtin';
+    if (skill.source === 'project')
+        return 'project';
+    const userDir = path.resolve(opts?.userDir || userSkillsDir());
+    const dir = path.resolve(skill.dir);
+    if (!dir.startsWith(userDir + path.sep))
+        return 'not-found'; // never delete outside the user scope
+    fs.rmSync(dir, { recursive: true, force: true });
+    return 'removed';
+}
+// ---- pack (store-upload artifact: zip with skills/<name>/ at its root) ----
+export function packSkill(dir, outPath) {
+    const abs = path.resolve(dir);
+    const skillMdPath = path.join(abs, 'SKILL.md');
+    if (!fs.existsSync(skillMdPath))
+        throw new Error(`${abs} is not a skill (no SKILL.md)`);
+    const parsed = parseSkillMd(fs.readFileSync(skillMdPath, 'utf-8'));
+    const name = parsed?.frontmatter.name || path.basename(abs);
+    if (!/^[A-Za-z0-9._-]+$/.test(name))
+        throw new Error(`unsafe skill name: ${name}`);
+    const files = [];
+    const walk = (current, rel) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (INSTALL_SKIP.has(entry.name) || entry.name === '.DS_Store')
+                continue;
+            const child = path.join(current, entry.name);
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory())
+                walk(child, childRel);
+            else if (entry.isFile())
+                files.push({ path: `skills/${name}/${childRel}`, data: fs.readFileSync(child) });
+        }
+    };
+    walk(abs, '');
+    const zipPath = outPath || path.resolve(process.cwd(), `${name}-skill.zip`);
+    fs.writeFileSync(zipPath, createZip(files));
+    return { zipPath, fileCount: files.length, name };
+}

package/dist/tools/background.js

@@ -0,0 +1,165 @@
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { killProcessTree, shellInvocation, spawnEnv } from '../shell.js';
+import { resolveSandboxMode, sandboxBackend, sandboxedInvocation } from '../sandbox.js';
+import { matchDangerousPattern } from './core.js';
+const handles = new Map();
+const MAX_TRACKED = 20;
+function newHandleId() {
+    return `bg-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e6).toString(36)}`;
+}
+function tailOf(logPath, bytes = 4000) {
+    try {
+        if (!fs.existsSync(logPath))
+            return '(no output yet)';
+        const stat = fs.statSync(logPath);
+        const start = Math.max(0, stat.size - bytes);
+        const fd = fs.openSync(logPath, 'r');
+        try {
+            const buf = Buffer.alloc(stat.size - start);
+            fs.readSync(fd, buf, 0, buf.length, start);
+            return (start > 0 ? '…(earlier output omitted)\n' : '') + buf.toString('utf-8');
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    catch (err) {
+        return `(could not read log: ${err.message})`;
+    }
+}
+export const StartBackgroundProcessTool = {
+    name: "Background Process Starter",
+    definition: {
+        type: "function",
+        function: {
+            name: "start_background_process",
+            description: "Start a long-lived command in the background without blocking: dev servers, watchers, long builds. Output is written to a log file you can read later.",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "The command to run in the background." },
+                    rationale: { type: "string", description: "Explain why this command should run in the background." }
+                },
+                required: ["command", "rationale"]
+            }
+        }
+    },
+    handler: async (args, config) => {
+        const command = String(args.command ?? '').trim();
+        if (!command)
+            return 'Error: "command" is required.';
+        // Same safety gate as the foreground shell tool.
+        const gateLabel = matchDangerousPattern(command);
+        if (gateLabel) {
+            return `Error: command blocked by AutoClaw safety policy (matched: ${gateLabel}). It was NOT started. If this task genuinely requires it, restart AutoClaw with --allow-dangerous.`;
+        }
+        // Same sandbox policy as the foreground shell tool.
+        const sandboxMode = resolveSandboxMode(config);
+        let target = shellInvocation(command);
+        if (sandboxMode !== 'danger-full-access') {
+            const backend = sandboxBackend();
+            if (!backend.available) {
+                return `Error: sandbox mode "${sandboxMode}" is configured but no sandbox backend is available: ${backend.detail}`;
+            }
+            const inv = sandboxedInvocation(command, sandboxMode, process.cwd());
+            if ('blocked' in inv) {
+                return `Error: sandbox mode "${sandboxMode}" cannot wrap this command: ${inv.detail}`;
+            }
+            target = inv;
+        }
+        for (const [id, h] of handles) {
+            if (h.exited && Date.now() - h.startedAt > 3600_000)
+                handles.delete(id);
+        }
+        if (handles.size >= MAX_TRACKED) {
+            return `Error: too many tracked background processes (${MAX_TRACKED}). Stop finished ones first or wait for them to exit.`;
+        }
+        const id = newHandleId();
+        const logDir = path.join(os.homedir(), '.autoclaw', 'output');
+        fs.mkdirSync(logDir, { recursive: true });
+        const logPath = path.join(logDir, `bg-${id}.log`);
+        const { file: logFile, args: spawnArgs } = target;
+        const out = fs.openSync(logPath, 'a');
+        let child;
+        try {
+            child = spawn(logFile, spawnArgs, {
+                windowsHide: true,
+                detached: process.platform !== 'win32',
+                env: spawnEnv(),
+                stdio: ['ignore', out, out]
+            });
+        }
+        catch (err) {
+            fs.closeSync(out);
+            return `Error: failed to start background process: ${err.message}`;
+        }
+        fs.closeSync(out);
+        const entry = { id, pid: child.pid, command, logPath, startedAt: Date.now(), exited: false, exitCode: null };
+        handles.set(id, entry);
+        child.on('exit', code => { entry.exited = true; entry.exitCode = code ?? null; });
+        child.unref();
+        return `Background process started.\n- handle id: ${id}\n- pid: ${child.pid}\n- log: ${logPath}\nUse check_background_process with this id to read output, or stop_background_process to terminate it.`;
+    }
+};
+export const CheckBackgroundProcessTool = {
+    name: "Background Process Checker",
+    definition: {
+        type: "function",
+        function: {
+            name: "check_background_process",
+            description: "Check a background process started with start_background_process: running/exited status and the tail of its output log.",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "The handle id returned by start_background_process." }
+                },
+                required: ["id"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const id = String(args.id ?? '');
+        const entry = handles.get(id);
+        if (!entry) {
+            return `Error: unknown background process id "${id}". Handles live for the current AutoClaw process only; the log file may still exist under ~/.autoclaw/output/.`;
+        }
+        const status = entry.exited
+            ? `exited (code: ${entry.exitCode ?? 'unknown'})`
+            : `running (pid: ${entry.pid}, ${Math.round((Date.now() - entry.startedAt) / 1000)}s elapsed)`;
+        return `Background process ${id}: ${status}\nCommand: ${entry.command}\nLog tail:\n${tailOf(entry.logPath)}`;
+    }
+};
+export const StopBackgroundProcessTool = {
+    name: "Background Process Stopper",
+    definition: {
+        type: "function",
+        function: {
+            name: "stop_background_process",
+            description: "Terminate a background process started with start_background_process (kills the whole process tree).",
+            parameters: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: "The handle id returned by start_background_process." }
+                },
+                required: ["id"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const id = String(args.id ?? '');
+        const entry = handles.get(id);
+        if (!entry) {
+            return `Error: unknown background process id "${id}".`;
+        }
+        if (entry.exited) {
+            return `Background process ${id} already exited (code: ${entry.exitCode ?? 'unknown'}). Log: ${entry.logPath}`;
+        }
+        if (entry.pid)
+            killProcessTree(entry.pid);
+        entry.exited = true;
+        return `Background process ${id} terminated.\nLog: ${entry.logPath}\nLog tail:\n${tailOf(entry.logPath)}`;
+    }
+};

package/dist/tools/core.js

@@ -3,6 +3,7 @@ import * as path from 'path';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import { execShellCommand } from '../shell.js';
+import { resolveSandboxMode, sandboxBackend, sandboxedInvocation } from '../sandbox.js';
 import * as os from 'os';
 const DEFAULT_SHELL_TIMEOUT_MS = 120000;
 const SHELL_MAX_BUFFER = 10 * 1024 * 1024;
@@ -75,6 +76,21 @@ export const ShellTool = {
             }
         }
         const timeoutMs = Number(config?.shellTimeout || process.env.AUTOCLOW_SHELL_TIMEOUT || DEFAULT_SHELL_TIMEOUT_MS);
+        // Sandbox policy: non-default modes wrap the invocation in a platform
+        // backend, or refuse (fail-closed) when no backend exists.
+        const sandboxMode = resolveSandboxMode(config);
+        let sandboxed;
+        if (sandboxMode !== 'danger-full-access') {
+            const backend = sandboxBackend();
+            if (!backend.available) {
+                return `Error: sandbox mode "${sandboxMode}" is configured but no sandbox backend is available: ${backend.detail}`;
+            }
+            const inv = sandboxedInvocation(args.command, sandboxMode, process.cwd());
+            if ('blocked' in inv) {
+                return `Error: sandbox mode "${sandboxMode}" cannot wrap this command: ${inv.detail}`;
+            }
+            sandboxed = inv;
+        }
         // Check for auto-confirm flag
         if (!config?.autoConfirm) {
             if (!process.stdin.isTTY) {
@@ -97,7 +113,7 @@ export const ShellTool = {
             console.log(chalk.gray("(Auto-confirming command execution due to --yes flag)"));
         }
         try {
-            const r = await execShellCommand(args.command, { timeoutMs, maxBuffer: SHELL_MAX_BUFFER });
+            const r = await execShellCommand(args.command, { timeoutMs, maxBuffer: SHELL_MAX_BUFFER, sandboxed });
             if (r.timedOut) {
                 return `Command timed out after ${timeoutMs}ms and was terminated.\nStdout: ${r.stdout}\nStderr: ${r.stderr}`;
             }

package/dist/tools/index.js

@@ -6,6 +6,9 @@ import { BrowserTool } from './browser.js';
 import { ScreenshotTool } from './screenshot.js';
 import { ImageTool } from './image.js';
 import { PromptOptimizerTool } from './prompt-optimizer.js';
+import { RenderImageTool } from './render-image.js';
+import { RenderPdfTool } from './render-pdf.js';
+import { CheckBackgroundProcessTool, StartBackgroundProcessTool, StopBackgroundProcessTool } from './background.js';
 // Central Registry of all available tools
 export const toolRegistry = [
     ShellTool,
@@ -18,7 +21,12 @@ export const toolRegistry = [
     NotifyTool,
     BrowserTool,
     ScreenshotTool,
-    ImageTool
+    ImageTool,
+    RenderImageTool,
+    RenderPdfTool,
+    StartBackgroundProcessTool,
+    CheckBackgroundProcessTool,
+    StopBackgroundProcessTool
 ];
 export function getToolDefinitions(config) {
     return toolRegistry

package/dist/tools/render-image.js

@@ -0,0 +1,135 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { render, renderSvg, renderAnimation } from 'takumi-js';
+import { resolveFontLoaders, describeFonts } from './takumi-fonts.js';
+const VALID_FORMATS = ['png', 'jpeg', 'webp', 'svg'];
+const VALID_ANIMATION_FORMATS = ['webp', 'gif', 'apng'];
+const toolDefinition = {
+    type: "function",
+    function: {
+        name: "render_image",
+        description: "Render an HTML template into a precise, deterministic image (PNG/JPEG/WebP), vector SVG, or animation (animated WebP/GIF/APNG from CSS @keyframes). Fully offline — no AI, no network, no browser, renders in milliseconds. Use this when exact text, layout, colors or data matter: OG/share cards, banners, badges, certificates, data cards, charts built from divs, simple motion graphics. Style with the 'tw' attribute (Tailwind v4 utilities, e.g. <div tw=\"w-full h-full bg-blue-500\">), inline styles, or a <style> block with regular CSS classes — Tailwind utilities placed in the class attribute are NOT compiled, always use tw for them. JavaScript is NOT executed; remote images in the template would require network. For artistic or photographic imagery use generate_image instead. CJK/emoji text needs fonts: common system fonts are auto-detected when font_paths is omitted, and registered families can be referenced via font-family.",
+        parameters: {
+            type: "object",
+            properties: {
+                template: {
+                    type: "string",
+                    description: "HTML fragment to render. Size the root to fill the canvas, e.g. '<div tw=\"w-full h-full flex flex-col items-center justify-center bg-linear-to-br from-blue-600 to-indigo-900 p-12\"><h1 tw=\"text-6xl font-bold text-white\">Monthly Report</h1></div>'. Style via the tw attribute (canonical Tailwind v4 names only — v3 names like bg-gradient-to-* are not supported, use bg-linear-to-*), inline styles, or a <style> block; a plain class attribute only matches CSS selectors, not Tailwind utilities."
+                },
+                css: {
+                    type: "string",
+                    description: "Optional CSS stylesheet applied before rendering, e.g. 'h1 { letter-spacing: 2px; }'."
+                },
+                width: {
+                    type: "integer",
+                    description: "Canvas width in px. Default 1200."
+                },
+                height: {
+                    type: "integer",
+                    description: "Canvas height in px. Default 630 (standard OG-image size)."
+                },
+                format: {
+                    type: "string",
+                    enum: VALID_FORMATS,
+                    description: "Output format. Default 'png'. 'svg' produces a vector document instead of a bitmap. Ignored when 'animation' is set."
+                },
+                animation: {
+                    type: "object",
+                    description: "Render an animated image instead of a static one: CSS @keyframes in the template (via a <style> block or the animation shorthand) are sampled across the scene duration. When set, 'format' is ignored — the container format comes from animation.format.",
+                    properties: {
+                        duration_ms: { type: "integer", description: "Scene duration in milliseconds. Default 1000." },
+                        fps: { type: "integer", description: "Frames per second. Default 30." },
+                        format: { type: "string", enum: VALID_ANIMATION_FORMATS, description: "Animation container format. Default 'webp'." }
+                    }
+                },
+                quality: {
+                    type: "integer",
+                    description: "0-100, JPEG/WebP only. Omit for lossless WebP / default JPEG quality."
+                },
+                font_paths: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Local font files (.ttf/.otf/.ttc/.woff2) to register. Omit to auto-detect common system fonts (incl. CJK/emoji). Pass [] to skip font loading (built-in Latin font only)."
+                },
+                output_path: {
+                    type: "string",
+                    description: "File path to write the rendered image. Parent directories are created automatically."
+                }
+            },
+            required: ["template", "output_path"]
+        }
+    }
+};
+const handler = async (args, config) => {
+    const template = typeof args.template === 'string' ? args.template : '';
+    if (!template.trim()) {
+        return "Error: 'template' is required — an HTML fragment to render.";
+    }
+    if (!args.output_path) {
+        return "Error: 'output_path' is required.";
+    }
+    const format = String(args.format || 'png').toLowerCase();
+    if (!VALID_FORMATS.includes(format)) {
+        return `Error: Invalid format '${format}'. Supported formats: ${VALID_FORMATS.join(", ")}.`;
+    }
+    const anim = args.animation && typeof args.animation === 'object' ? args.animation : null;
+    if (anim && anim.format != null && !VALID_ANIMATION_FORMATS.includes(String(anim.format).toLowerCase())) {
+        return `Error: Invalid animation format '${anim.format}'. Supported: ${VALID_ANIMATION_FORMATS.join(", ")}.`;
+    }
+    const width = args.width || 1200;
+    const height = args.height || 630;
+    const resolvedPath = path.resolve(process.cwd(), args.output_path);
+    try {
+        const resolved = resolveFontLoaders(args.font_paths);
+        const fontsInfo = describeFonts(resolved);
+        fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+        if (anim) {
+            const animFormat = String(anim.format || 'webp').toLowerCase();
+            const options = {
+                width,
+                height,
+                fps: anim.fps || 30,
+                format: animFormat,
+                scenes: [{ node: template, durationMs: anim.duration_ms || 1000 }]
+            };
+            if (resolved.fonts.length > 0)
+                options.fonts = resolved.fonts;
+            if (args.css)
+                options.css = args.css;
+            const bytes = await renderAnimation(options);
+            const buffer = Buffer.from(bytes);
+            fs.writeFileSync(resolvedPath, buffer);
+            return `Rendered animation (${width}x${height} ${animFormat.toUpperCase()}, ${anim.fps || 30}fps, ${anim.duration_ms || 1000}ms, ${buffer.length} bytes) saved to ${resolvedPath}. Fonts: ${fontsInfo}`;
+        }
+        if (format === 'svg') {
+            const options = { width, height };
+            if (resolved.fonts.length > 0)
+                options.fonts = resolved.fonts;
+            if (args.css)
+                options.css = args.css;
+            const svg = await renderSvg(template, options);
+            fs.writeFileSync(resolvedPath, svg, 'utf-8');
+            return `Rendered vector SVG (${width}x${height}, ${Buffer.byteLength(svg)} bytes) saved to ${resolvedPath}. Fonts: ${fontsInfo}`;
+        }
+        const options = { width, height, format };
+        if (resolved.fonts.length > 0)
+            options.fonts = resolved.fonts;
+        if (args.css)
+            options.css = args.css;
+        if (args.quality != null && (format === 'jpeg' || format === 'webp')) {
+            options.quality = args.quality;
+        }
+        const bytes = await render(template, options);
+        const buffer = Buffer.from(bytes);
+        fs.writeFileSync(resolvedPath, buffer);
+        return `Rendered image (${width}x${height} ${format.toUpperCase()}, ${buffer.length} bytes) saved to ${resolvedPath}. Fonts: ${fontsInfo}`;
+    }
+    catch (err) {
+        return `Error rendering image: ${err?.message || err}`;
+    }
+};
+export const RenderImageTool = {
+    name: "Image Renderer (Takumi)",
+    definition: toolDefinition,
+    handler
+};