zoe-agent 0.3.1

package/dist/tools/core.js

@@ -0,0 +1,244 @@
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+export const ShellTool = {
+    name: "Shell Execution",
+    risk: "destructive",
+    definition: {
+        type: "function",
+        function: {
+            name: "execute_shell_command",
+            description: "Execute a shell command on the host machine. Use this to run scripts, list files, or interact with the system.",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "The shell command to execute." },
+                    rationale: { type: "string", description: "Explain why you are running this command." }
+                },
+                required: ["command", "rationale"]
+            }
+        }
+    },
+    // Runs via `spawn(shell:true)` (same shell as the former `exec`) so stdout
+    // can stream live via onUpdate; the resolved string matches the old format
+    // (stdout + optional "Stderr:" suffix) so headless output is unchanged.
+    handler: async (args, _config, extra) => {
+        const onUpdate = extra?.onUpdate;
+        return new Promise((resolve) => {
+            let stdout = '';
+            let stderr = '';
+            const child = spawn(args.command, { shell: true });
+            child.stdout?.on('data', (data) => {
+                const chunk = data.toString();
+                stdout += chunk;
+                if (onUpdate)
+                    onUpdate({ message: chunk });
+            });
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            child.on('error', (err) => {
+                resolve(`Command failed: ${err.message}\nStdout: ${stdout}\nStderr: ${stderr}`);
+            });
+            child.on('close', (code) => {
+                if (code === 0) {
+                    resolve(stdout + (stderr ? `\nStderr: ${stderr}` : ''));
+                }
+                else {
+                    resolve(`Command failed: ${args.command} (exit ${code ?? 'null'})\nStdout: ${stdout}\nStderr: ${stderr}`);
+                }
+            });
+        });
+    }
+};
+export const ReadFileTool = {
+    name: "File Reader",
+    risk: "safe",
+    definition: {
+        type: "function",
+        function: {
+            name: "read_file",
+            description: "Read the content of a file.",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "The path to the file to read." }
+                },
+                required: ["path"]
+            }
+        }
+    },
+    handler: async (args) => {
+        try {
+            const content = await fs.readFile(args.path, 'utf-8');
+            return content;
+        }
+        catch (error) {
+            return `Error reading file: ${error.message}`;
+        }
+    }
+};
+/** Files larger than this (bytes OR lines) skip the inline diff to avoid
+ *  dumping a huge render into the TUI. */
+const DIFF_BYTE_CAP = 64 * 1024;
+const DIFF_LINE_CAP = 2000;
+/** Line count that treats a trailing newline as the end of the last line, not
+ *  the start of an empty one: "a\nb\n" is 2 lines, "a\nb" is 2, "a\n" is 1. */
+const lineCount = (text) => {
+    if (text === "")
+        return 0;
+    const newlines = text.split("\n").length - 1;
+    return text.endsWith("\n") ? newlines : newlines + 1;
+};
+/** Temps younger than this are assumed to belong to a live write (possibly a
+ *  concurrent process) and are left alone; only older orphans are swept. */
+const STALE_TEMP_AGE_MS = 60_000;
+/** Remove orphaned `.zoe-*.tmp` write temps for `basename` in `dir` — left
+ *  behind by a hard kill (SIGKILL/power loss) in the window between temp-write
+ *  and rename, which the handler's catch block can't reach. Only temps older
+ *  than STALE_TEMP_AGE_MS are removed, so a peer's in-flight temp is never
+ *  touched (no cross-process race). Best-effort; errors swallowed. */
+async function cleanStaleTemps(dir, basename) {
+    let entries;
+    try {
+        entries = await fs.readdir(dir);
+    }
+    catch {
+        return; // dir doesn't exist yet (new file in a new dir) — nothing to sweep
+    }
+    const prefix = `${basename}.zoe-`;
+    const cutoff = Date.now() - STALE_TEMP_AGE_MS;
+    await Promise.all(entries
+        .filter((e) => e.startsWith(prefix) && e.endsWith(".tmp"))
+        .map(async (e) => {
+        const full = path.join(dir, e);
+        try {
+            const st = await fs.stat(full);
+            if (st.mtimeMs < cutoff)
+                await fs.unlink(full);
+        }
+        catch { /* raced with another sweeper or already gone — ignore */ }
+    }));
+}
+export const WriteFileTool = {
+    name: "File Writer",
+    risk: "edit",
+    definition: {
+        type: "function",
+        function: {
+            name: "write_file",
+            description: "Write content to a file. Overwrites existing files.",
+            parameters: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "The path to the file to write." },
+                    content: { type: "string", description: "The content to write." }
+                },
+                required: ["path", "content"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const filePath = args.path;
+        const newContent = args.content;
+        // 1. Stat the target (size only — never slurp a huge file). Read the old
+        //    content ONLY when neither side already exceeds the byte/line caps, so a
+        //    large write doesn't pay for a pointless read. The line cap applies to
+        //    BOTH sides — a small-but-thousands-of-lines file diffs just as badly.
+        let fileExists = false;
+        let oldBytes = 0;
+        try {
+            const st = await fs.stat(filePath);
+            fileExists = true;
+            oldBytes = st.size;
+        }
+        catch {
+            // absent ⇒ new file
+        }
+        const isNewFile = !fileExists;
+        const newBytes = Buffer.byteLength(newContent, "utf-8");
+        const newOverCap = newBytes > DIFF_BYTE_CAP || lineCount(newContent) > DIFF_LINE_CAP;
+        const oldByteOverCap = oldBytes > DIFF_BYTE_CAP;
+        let oldContent = null;
+        let oldLineOverCap = false;
+        if (!newOverCap && !oldByteOverCap) {
+            try {
+                oldContent = await fs.readFile(filePath, "utf-8");
+                oldLineOverCap = lineCount(oldContent) > DIFF_LINE_CAP;
+            }
+            catch {
+                // absent ⇒ new file (oldContent stays null)
+            }
+        }
+        const overCap = newOverCap || oldByteOverCap || oldLineOverCap;
+        // 2. Atomic write: temp file in the SAME directory (same filesystem ⇒
+        //    fs.rename is atomic on POSIX), then rename. On any failure the temp
+        //    is unlinked and the original is never partially written. A same-path
+        //    temp orphaned by a prior hard kill is swept first.
+        const dir = path.dirname(filePath);
+        const tmpPath = `${filePath}.zoe-${randomUUID().slice(0, 8)}.tmp`;
+        await cleanStaleTemps(dir, path.basename(filePath));
+        try {
+            await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(tmpPath, newContent, "utf-8");
+            await fs.rename(tmpPath, filePath);
+        }
+        catch (error) {
+            try {
+                await fs.unlink(tmpPath);
+            }
+            catch { /* temp may not have been created */ }
+            return { output: `Error writing file: ${error.message}`, success: false };
+        }
+        // 3. Build metadata for the diff viewer. `overCap` already accounts for both
+        //    sides (byte AND line), so a small edit to a large/many-line file skips
+        //    the diff instead of storing/rendering the whole old file. Full content
+        //    is omitted when over cap.
+        const metadata = overCap
+            ? {
+                path: filePath,
+                isNewFile,
+                byteDelta: newBytes - oldBytes,
+                diffSkipped: true,
+                skipReason: `file exceeds ${DIFF_BYTE_CAP} bytes or ${DIFF_LINE_CAP} lines`,
+            }
+            : {
+                path: filePath,
+                oldContent,
+                newContent,
+                isNewFile,
+                byteDelta: newBytes - oldBytes,
+            };
+        return {
+            output: `Successfully wrote to ${filePath} (${lineCount(oldContent ?? "")} -> ${lineCount(newContent)} lines)`,
+            success: true,
+            metadata,
+        };
+    }
+};
+export const DateTimeTool = {
+    name: "Date & Time",
+    risk: "safe",
+    definition: {
+        type: "function",
+        function: {
+            name: "get_current_datetime",
+            description: "Get the current system date and time. Use this when the user refers to relative dates (like 'today', 'next week', 'this March') to ensure accuracy.",
+            parameters: {
+                type: "object",
+                properties: {},
+                required: []
+            }
+        }
+    },
+    handler: async () => {
+        const now = new Date();
+        return JSON.stringify({
+            iso: now.toISOString(),
+            local: now.toLocaleString(),
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+            weekday: now.toLocaleDateString('en-US', { weekday: 'long' })
+        }, null, 2);
+    }
+};

package/dist/tools/email.d.ts

@@ -0,0 +1,2 @@
+import { ToolModule } from './interface.js';
+export declare const EmailTool: ToolModule;

package/dist/tools/email.js

@@ -0,0 +1,61 @@
+import nodemailer from 'nodemailer';
+export const EmailTool = {
+    name: "Email Service",
+    risk: "communications",
+    configKeys: ["smtpHost", "smtpPort", "smtpUser", "smtpPass", "smtpFrom"],
+    definition: {
+        type: "function",
+        function: {
+            name: "send_email",
+            description: "Send an email using configured SMTP settings. Can include optional file attachments.",
+            parameters: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Recipient email address." },
+                    subject: { type: "string", description: "Email subject." },
+                    body: { type: "string", description: "Email body content (text)." },
+                    attachments: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional list of local file paths to attach to the email."
+                    }
+                },
+                required: ["to", "subject", "body"]
+            }
+        }
+    },
+    handler: async (args, config) => {
+        // Validate config
+        if (!config?.smtpHost || !config?.smtpUser || !config?.smtpPass) {
+            return "Error: Email tool is not configured. Please run 'zoe setup' to configure SMTP settings.";
+        }
+        try {
+            const transporter = nodemailer.createTransport({
+                host: config.smtpHost,
+                port: parseInt(config.smtpPort || '587'),
+                secure: parseInt(config.smtpPort) === 465, // true for 465, false for other ports
+                auth: {
+                    user: config.smtpUser,
+                    pass: config.smtpPass,
+                },
+            });
+            const emailAttachments = args.attachments?.map((filePath) => ({
+                path: filePath
+            })) || [];
+            const info = await transporter.sendMail({
+                from: config.smtpFrom || config.smtpUser, // sender address
+                to: args.to, // list of receivers
+                subject: args.subject, // Subject line
+                text: args.body, // plain text body
+                attachments: emailAttachments
+            });
+            return `Email sent successfully. Message ID: ${info.messageId}`;
+        }
+        catch (error) {
+            // Return detailed error info for debugging
+            const code = error.code ? `[Code: ${error.code}] ` : '';
+            const response = error.response ? ` (Server Response: ${error.response})` : '';
+            return `Failed to send email: ${code}${error.message}${response}`;
+        }
+    }
+};

package/dist/tools/image.d.ts

@@ -0,0 +1,2 @@
+import { ToolModule } from './interface.js';
+export declare const ImageTool: ToolModule;

package/dist/tools/image.js

@@ -0,0 +1,257 @@
+import { OpenAI } from 'openai';
+import chalk from 'chalk';
+import * as fs from 'fs';
+import * as path from 'path';
+const toolDefinition = {
+    type: "function",
+    function: {
+        name: "generate_image",
+        description: "Generates or edits images using AI models (DALL-E 3/2). Supports text-to-image, image variation, and image editing. Allows control over size, resolution (quality), and model selection.",
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: {
+                    type: "string",
+                    description: "Text description of the desired image. Required for text-to-image and edit modes."
+                },
+                image_path: {
+                    type: "string",
+                    description: "Path to an existing image file (local path). Required for variation and editing modes."
+                },
+                mask_path: {
+                    type: "string",
+                    description: "Path to a mask image file (local path). Optional, used only for editing."
+                },
+                mode: {
+                    type: "string",
+                    enum: ["text-to-image", "variation", "edit"],
+                    description: "Operation mode. Inferred if not provided."
+                },
+                model: {
+                    type: "string",
+                    description: "The AI model to use. 'dall-e-3' for high quality (default), 'dall-e-2' for editing, or a custom model like 'doubao-seedream-4-5-251128'.",
+                    default: "dall-e-3"
+                },
+                n: {
+                    type: "integer",
+                    description: "Number of images to generate. Default is 1.",
+                    default: 1
+                },
+                size: {
+                    type: "string",
+                    description: "Resolution/Aspect Ratio. YOU should infer the best size based on the prompt content.\n- DALL-E 3: '1024x1024' (Square), '1792x1024' (Landscape), '1024x1792' (Portrait).\n- Doubao/High-Res: MUST be >3.6M pixels. Use '2048x2048' (Square), '2560x1440' (Landscape), '1440x2560' (Portrait).",
+                    default: "1024x1024"
+                },
+                quality: {
+                    type: "string",
+                    enum: ["standard", "hd"],
+                    description: "Image quality (DALL-E 3 only). 'hd' creates more detailed images. Default is 'standard'.",
+                    default: "standard"
+                },
+                style: {
+                    type: "string",
+                    enum: ["vivid", "natural"],
+                    description: "Image style (DALL-E 3 only). Default is 'vivid'.",
+                    default: "vivid"
+                },
+                output_dir: {
+                    type: "string",
+                    description: "Directory to save the generated images. Defaults to current directory."
+                }
+            },
+            required: []
+        }
+    }
+};
+async function downloadImage(url, destPath) {
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`Failed to download image: ${response.statusText}`);
+    const buffer = await response.arrayBuffer();
+    fs.writeFileSync(destPath, Buffer.from(buffer));
+}
+const handler = async (args, config) => {
+    const apiKey = config.imageApiKey || config.apiKey || process.env.OPENAI_API_KEY;
+    const baseURL = config.imageBaseUrl || config.baseUrl || process.env.OPENAI_COMPAT_BASE_URL || process.env.OPENAI_BASE_URL;
+    if (!apiKey) {
+        return "Error: Image Service API Key is missing. Please configure it in .zoe/setting.json (imageApiKey or apiKey).";
+    }
+    const client = new OpenAI({
+        apiKey: apiKey,
+        baseURL: baseURL
+    });
+    const { prompt, image_path, mask_path, output_dir = "." } = args;
+    const n = args.n || config.imageN || 1;
+    // Model-specific default size
+    let mode = args.mode;
+    let model = args.model;
+    if (config.imageModel && (!model || model === 'dall-e-3')) {
+        model = config.imageModel;
+    }
+    model = model || "dall-e-3";
+    let defaultSize = "1024x1024";
+    if (model.toLowerCase().includes("doubao")) {
+        defaultSize = "2048x2048";
+    }
+    const size = args.size || config.imageSize || defaultSize;
+    const quality = args.quality || config.imageQuality || "standard";
+    const style = args.style || config.imageStyle || "vivid";
+    // Infer mode if not provided
+    if (!mode) {
+        if (image_path && mask_path)
+            mode = "edit";
+        else if (image_path)
+            mode = "variation";
+        else
+            mode = "text-to-image";
+    }
+    // Model-specific validations
+    if (mode === "text-to-image") {
+        // DALL-E 3 Validation
+        if (model === "dall-e-3") {
+            const validSizes = ["1024x1024", "1024x1792", "1792x1024"];
+            if (!validSizes.includes(size)) {
+                return `Error: Invalid size '${size}' for DALL-E 3. Supported sizes are: ${validSizes.join(", ")}.`;
+            }
+        }
+        // DALL-E 2 Validation
+        else if (model === "dall-e-2") {
+            const validSizes = ["256x256", "512x512", "1024x1024"];
+            if (!validSizes.includes(size)) {
+                return `Error: Invalid size '${size}' for DALL-E 2. Supported sizes are: ${validSizes.join(", ")}.`;
+            }
+        }
+    }
+    else {
+        // Variation and Edit only support DALL-E 2 currently
+        if (model === "dall-e-3") {
+            console.log("Note: DALL-E 3 does not support variation/edit. Falling back to DALL-E 2.");
+            model = "dall-e-2";
+        }
+    }
+    // Resolve output directory
+    const resolvedOutputDir = path.resolve(process.cwd(), output_dir);
+    if (!fs.existsSync(resolvedOutputDir)) {
+        fs.mkdirSync(resolvedOutputDir, { recursive: true });
+    }
+    const generatedFiles = [];
+    try {
+        if (mode === "text-to-image") {
+            if (!prompt)
+                return "Error: 'prompt' is required for text-to-image mode.";
+            console.log(`Generating ${n} image(s) with ${model} (${size}, ${quality})...`);
+            if (model === "dall-e-3") {
+                for (let i = 0; i < n; i++) {
+                    const response = await client.images.generate({
+                        model: "dall-e-3",
+                        prompt: prompt,
+                        n: 1, // DALL-E 3 constraint
+                        size: size,
+                        quality: quality,
+                        style: style,
+                        response_format: "url"
+                    });
+                    const imageUrl = response.data?.[0]?.url;
+                    if (imageUrl) {
+                        const fileName = `generated-${Date.now()}-${i + 1}.png`;
+                        const filePath = path.join(resolvedOutputDir, fileName);
+                        await downloadImage(imageUrl, filePath);
+                        generatedFiles.push(filePath);
+                    }
+                }
+            }
+            else {
+                // DALL-E 2 or Custom Model
+                const response = await client.images.generate({
+                    model: model,
+                    prompt: prompt,
+                    n: n,
+                    size: size,
+                    response_format: "url"
+                });
+                const data = response.data || [];
+                for (let i = 0; i < data.length; i++) {
+                    const imageUrl = data[i].url;
+                    if (imageUrl) {
+                        const fileName = `generated-${Date.now()}-${i + 1}.png`;
+                        const filePath = path.join(resolvedOutputDir, fileName);
+                        await downloadImage(imageUrl, filePath);
+                        generatedFiles.push(filePath);
+                    }
+                }
+            }
+        }
+        else if (mode === "variation") {
+            if (!image_path)
+                return "Error: 'image_path' is required for variation mode.";
+            if (!fs.existsSync(image_path))
+                return `Error: Image file not found at ${image_path}`;
+            console.log(`Generating ${n} variation(s) with ${model}...`);
+            const response = await client.images.createVariation({
+                image: fs.createReadStream(image_path),
+                n: n,
+                model: "dall-e-2", // Explicitly set model just in case, though it's the default/only option
+                size: size,
+                response_format: "url"
+            });
+            const data = response.data || [];
+            for (let i = 0; i < data.length; i++) {
+                const imageUrl = data[i].url;
+                if (imageUrl) {
+                    const fileName = `variation-${Date.now()}-${i + 1}.png`;
+                    const filePath = path.join(resolvedOutputDir, fileName);
+                    await downloadImage(imageUrl, filePath);
+                    generatedFiles.push(filePath);
+                }
+            }
+        }
+        else if (mode === "edit") {
+            if (!image_path)
+                return "Error: 'image_path' is required for edit mode.";
+            if (!prompt)
+                return "Error: 'prompt' is required for edit mode.";
+            if (!fs.existsSync(image_path))
+                return `Error: Image file not found at ${image_path}`;
+            console.log(`Editing image with ${model}...`);
+            const params = {
+                image: fs.createReadStream(image_path),
+                prompt: prompt,
+                n: n,
+                model: "dall-e-2",
+                size: size,
+                response_format: "url"
+            };
+            if (mask_path && fs.existsSync(mask_path)) {
+                params.mask = fs.createReadStream(mask_path);
+            }
+            const response = await client.images.edit(params);
+            const data = response.data || [];
+            for (let i = 0; i < data.length; i++) {
+                const imageUrl = data[i].url;
+                if (imageUrl) {
+                    const fileName = `edited-${Date.now()}-${i + 1}.png`;
+                    const filePath = path.join(resolvedOutputDir, fileName);
+                    await downloadImage(imageUrl, filePath);
+                    generatedFiles.push(filePath);
+                }
+            }
+        }
+        else {
+            return `Error: Unknown mode '${mode}'.`;
+        }
+        return `Successfully generated ${generatedFiles.length} image(s):\n${generatedFiles.join('\n')}`;
+    }
+    catch (error) {
+        console.error(chalk.red(`Image Generation Failed: ${error.message}`));
+        if (error.response && error.response.data) {
+            console.error(chalk.dim(JSON.stringify(error.response.data)));
+        }
+        return `Error generating image: ${error.message}`;
+    }
+};
+export const ImageTool = {
+    name: "Image Generation",
+    risk: "edit",
+    definition: toolDefinition,
+    handler: handler
+};

package/dist/tools/index.d.ts

@@ -0,0 +1,2 @@
+import { ToolModule } from './interface.js';
+export declare const builtInTools: ToolModule[];

package/dist/tools/index.js

@@ -0,0 +1,88 @@
+import { ShellTool, ReadFileTool, WriteFileTool, DateTimeTool } from './core.js';
+import { TodoTool } from './todos.js';
+import { EmailTool } from './email.js';
+import { SearchTool } from './search.js';
+import { NotifyTool } from './notify.js';
+import { BrowserTool } from './browser.js';
+import { ScreenshotTool } from './screenshot.js';
+import { ImageTool } from './image.js';
+import { PromptOptimizerTool } from './prompt-optimizer.js';
+import { getSkillRegistry } from '../skills/index.js';
+import { limitSkillBody } from '../skills/types.js';
+const UseSkillTool = {
+    name: "Skill Invocation",
+    risk: "safe",
+    definition: {
+        type: "function",
+        function: {
+            name: "use_skill",
+            description: "Load and activate a specific skill to gain specialized knowledge and procedures. Use when the user's request matches a skill's description.",
+            parameters: {
+                type: "object",
+                properties: {
+                    skill_name: {
+                        type: "string",
+                        description: "Name of the skill to activate (e.g. 'docker-ops', 'k8s-deploy')"
+                    },
+                    args: {
+                        type: "object",
+                        description: "Optional arguments to pass to the skill (e.g. {environment: 'staging', service: 'myapp'})",
+                        properties: {}
+                    }
+                },
+                required: ["skill_name"]
+            }
+        }
+    },
+    handler: async (args) => {
+        const registry = getSkillRegistry();
+        if (!registry)
+            return "Error: Skill system not initialized.";
+        const { skill_name, args: skillArgs } = args;
+        const skill = registry.get(skill_name);
+        if (!skill) {
+            return `Error: Skill '${skill_name}' not found. Available skills: ${registry.getAll().map(s => s.name).join(', ')}`;
+        }
+        const body = await registry.getBody(skill_name);
+        if (!body)
+            return `Error: Skill '${skill_name}' has no content.`;
+        // If skillArgs provided, substitute positional variables
+        let resolvedBody = body;
+        if (skillArgs && typeof skillArgs === 'object') {
+            const argsValues = Object.values(skillArgs);
+            if (argsValues.length > 0) {
+                const { substituteArgs } = await import('../skills/args.js');
+                resolvedBody = substituteArgs(body, {
+                    positional: argsValues.map(String),
+                    raw: argsValues.join(' '),
+                });
+            }
+        }
+        // Enforce body size limits
+        const { body: limitedBody, truncated, originalTokenEstimate, finalTokenEstimate } = limitSkillBody(resolvedBody);
+        let result = `# ${skill.name} Skill Activated\n\n${limitedBody}`;
+        if (truncated) {
+            result += `\n\n> Note: Skill body was truncated (${originalTokenEstimate} -> ${finalTokenEstimate} estimated tokens). The skill may not function as intended.`;
+        }
+        if (skillArgs && Object.keys(skillArgs).length > 0) {
+            result += `\n\n## Skill Arguments\n${JSON.stringify(skillArgs, null, 2)}`;
+        }
+        return result;
+    }
+};
+// Central Registry of all available tools
+export const builtInTools = [
+    ShellTool,
+    ReadFileTool,
+    WriteFileTool,
+    DateTimeTool,
+    TodoTool,
+    PromptOptimizerTool,
+    EmailTool,
+    SearchTool,
+    NotifyTool,
+    BrowserTool,
+    ScreenshotTool,
+    ImageTool,
+    UseSkillTool
+];

package/dist/tools/interface.d.ts

@@ -0,0 +1,22 @@
+import type { ToolRiskCategory, ToolContext, ToolResult } from "../core/types.js";
+/** Optional execution context pieces a caller (the agent loop) can pass in. */
+export type ToolExecExtra = Pick<ToolContext, "onUpdate" | "signal">;
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: "execute_shell_command" | "read_file" | "write_file" | "send_email" | string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+    };
+}
+export interface ToolModule {
+    name: string;
+    configKeys?: string[];
+    risk?: ToolRiskCategory;
+    definition: ToolDefinition;
+    handler: (args: any, config?: any, extra?: ToolExecExtra) => Promise<string | ToolResult>;
+}