qlogicagent 0.2.1 → 0.4.0

package/dist/skills/tools/config-tool.js

@@ -1,143 +0,0 @@
-// ============================================================
-// Config Tool — agent configuration management (read/write preferences).
-// Reference: claude-code-haha/src/tools/ConfigTool/ConfigTool.ts
-// Category: system
-// ============================================================
-export const CONFIG_TOOL_NAME = "config";
-export const CONFIG_TOOL_SCHEMA = {
-    type: "object",
-    properties: {
-        action: {
-            type: "string",
-            enum: ["get", "set", "list", "reset"],
-            description: "Action:\n" +
-                "- get: Read a config setting\n" +
-                "- set: Write a config setting\n" +
-                "- list: List all available settings\n" +
-                "- reset: Reset a setting to default",
-        },
-        key: {
-            type: "string",
-            description: "Config key path (e.g. 'model', 'language', 'theme', 'permissions.defaultMode'). " +
-                "Required for get/set/reset.",
-        },
-        value: {
-            description: "Value to set. Type depends on the setting. Required for 'set' action.",
-        },
-    },
-    required: ["action"],
-};
-/** Keys that cannot be modified by LLM (security-critical) */
-export const CONFIG_READONLY_KEYS = [
-    "permissions.securityPolicy",
-    "api.key",
-    "api.secret",
-    "auth.token",
-    "system.adminMode",
-];
-export function createConfigTool(deps) {
-    return {
-        name: CONFIG_TOOL_NAME,
-        label: "Config",
-        description: "Read and write agent configuration settings. " +
-            "Supports preferences like model selection, language, theme, tool enablement, etc. " +
-            "Security-critical settings (API keys, permissions) are read-only. " +
-            "Changes persist across sessions.",
-        parameters: CONFIG_TOOL_SCHEMA,
-        execute: async (_toolCallId, params) => {
-            switch (params.action) {
-                case "get": {
-                    if (!params.key) {
-                        return { content: [{ type: "text", text: "Error: key is required for get." }], details: { type: "config", error: "missing_key" } };
-                    }
-                    if (deps.isValidKey && !deps.isValidKey(params.key)) {
-                        return { content: [{ type: "text", text: `Error: unknown config key "${params.key}". Use action='list' to see available settings.` }], details: { type: "config", error: "unknown_key" } };
-                    }
-                    const result = await deps.getConfig(params.key);
-                    if (!result.success) {
-                        return { content: [{ type: "text", text: `Error: ${result.error}` }], details: { type: "config", error: result.error } };
-                    }
-                    const s = result.setting;
-                    const lines = [
-                        `${s.key} = ${JSON.stringify(s.value)}`,
-                        `  Type: ${s.type}${s.options ? ` (${s.options.join(" | ")})` : ""}`,
-                        `  ${s.description}`,
-                    ];
-                    if (s.readOnly)
-                        lines.push("  ⚠️ Read-only (cannot be changed)");
-                    return {
-                        content: [{ type: "text", text: lines.join("\n") }],
-                        details: { type: "config", action: "get", key: params.key, value: s.value },
-                    };
-                }
-                case "set": {
-                    if (!params.key) {
-                        return { content: [{ type: "text", text: "Error: key is required for set." }], details: { type: "config", error: "missing_key" } };
-                    }
-                    if (params.value === undefined) {
-                        return { content: [{ type: "text", text: "Error: value is required for set." }], details: { type: "config", error: "missing_value" } };
-                    }
-                    // Block security-critical keys
-                    if (CONFIG_READONLY_KEYS.includes(params.key)) {
-                        return {
-                            content: [{ type: "text", text: `Error: "${params.key}" is a security-critical setting and cannot be modified.` }],
-                            details: { type: "config", error: "readonly_key" },
-                        };
-                    }
-                    if (deps.isValidKey && !deps.isValidKey(params.key)) {
-                        return { content: [{ type: "text", text: `Error: unknown config key "${params.key}".` }], details: { type: "config", error: "unknown_key" } };
-                    }
-                    const result = await deps.setConfig(params.key, params.value);
-                    if (!result.success) {
-                        return { content: [{ type: "text", text: `Error: ${result.error}` }], details: { type: "config", error: result.error } };
-                    }
-                    return {
-                        content: [{ type: "text", text: `Updated "${params.key}": ${JSON.stringify(result.previousValue)} → ${JSON.stringify(params.value)}` }],
-                        details: { type: "config", action: "set", key: params.key, previousValue: result.previousValue, newValue: params.value },
-                    };
-                }
-                case "list": {
-                    const result = await deps.listConfig();
-                    if (!result.settings || result.settings.length === 0) {
-                        return { content: [{ type: "text", text: "No config settings available." }], details: { type: "config", action: "list", count: 0 } };
-                    }
-                    const lines = [`Available settings (${result.settings.length}):`, ""];
-                    for (const s of result.settings) {
-                        const ro = s.readOnly ? " [read-only]" : "";
-                        const val = JSON.stringify(s.value);
-                        lines.push(`  ${s.key} = ${val}${ro}`);
-                        lines.push(`    ${s.description}`);
-                    }
-                    return {
-                        content: [{ type: "text", text: lines.join("\n") }],
-                        details: { type: "config", action: "list", count: result.settings.length },
-                    };
-                }
-                case "reset": {
-                    if (!params.key) {
-                        return { content: [{ type: "text", text: "Error: key is required for reset." }], details: { type: "config", error: "missing_key" } };
-                    }
-                    if (CONFIG_READONLY_KEYS.includes(params.key)) {
-                        return {
-                            content: [{ type: "text", text: `Error: "${params.key}" cannot be reset (security-critical).` }],
-                            details: { type: "config", error: "readonly_key" },
-                        };
-                    }
-                    const result = await deps.resetConfig(params.key);
-                    if (!result.success) {
-                        return { content: [{ type: "text", text: `Error: ${result.error}` }], details: { type: "config", error: result.error } };
-                    }
-                    return {
-                        content: [{ type: "text", text: `Reset "${params.key}" to default: ${JSON.stringify(result.setting?.value)}` }],
-                        details: { type: "config", action: "reset", key: params.key, value: result.setting?.value },
-                    };
-                }
-                default:
-                    return {
-                        content: [{ type: "text", text: `Error: unknown action "${params.action}".` }],
-                        details: { type: "config", error: "unknown_action" },
-                    };
-            }
-        },
-    };
-}

package/dist/skills/tools/cron-tool.d.ts

@@ -1,116 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const CRON_TOOL_NAME: "cron";
-export type CronAction = "create" | "list" | "get" | "update" | "delete" | "pause" | "resume" | "trigger";
-export interface CronToolParams {
-    action: CronAction;
-    /** Job ID (required for get/update/delete/pause/resume/trigger) */
-    jobId?: string;
-    /** Task prompt to execute on schedule */
-    prompt?: string;
-    /** Cron expression or shorthand ('5m', '1h', '0 9 * * *') */
-    schedule?: string;
-    /** Human-readable job name */
-    name?: string;
-    /** Repeat count (null = infinite) */
-    repeat?: number | null;
-    /** Allowed tools for the scheduled task */
-    allowedTools?: string[];
-    /** Whether the job is enabled */
-    enabled?: boolean;
-}
-export declare const CRON_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["create", "list", "get", "update", "delete", "pause", "resume", "trigger"];
-            readonly description: "CRUD action: create/list/get/update/delete/pause/resume/trigger.";
-        };
-        readonly jobId: {
-            readonly type: "string";
-            readonly description: "Job ID. Required for get/update/delete/pause/resume/trigger.";
-        };
-        readonly prompt: {
-            readonly type: "string";
-            readonly description: "Task prompt to execute on schedule. Required for create.";
-        };
-        readonly schedule: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly name: {
-            readonly type: "string";
-            readonly description: "Human-readable job name.";
-        };
-        readonly repeat: {
-            readonly type: "number";
-            readonly description: "Number of times to repeat (null = infinite). Default: null.";
-        };
-        readonly allowedTools: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "string";
-            };
-            readonly description: "Tools the scheduled task is allowed to use.";
-        };
-        readonly enabled: {
-            readonly type: "boolean";
-            readonly description: "Whether the job is enabled (for update).";
-        };
-    };
-    readonly required: readonly ["action"];
-};
-export interface CronJob {
-    id: string;
-    name: string;
-    prompt: string;
-    schedule: string;
-    scheduleDisplay: string;
-    state: "scheduled" | "paused";
-    enabled: boolean;
-    repeat: {
-        times: number | null;
-        completed: number;
-    };
-    nextRunAt?: string;
-    lastRunAt?: string;
-    lastStatus?: "success" | "error" | null;
-    allowedTools?: string[];
-}
-export interface CronResult {
-    success: boolean;
-    job?: CronJob;
-    jobs?: CronJob[];
-    error?: string;
-}
-/**
- * Host-provided cron scheduler backend.
- * Jobs are persisted locally and survive restarts.
- */
-export interface CronToolDeps {
-    createJob(params: {
-        prompt: string;
-        schedule: string;
-        name?: string;
-        repeat?: number | null;
-        allowedTools?: string[];
-    }): Promise<CronResult>;
-    listJobs(): Promise<CronResult>;
-    getJob(jobId: string): Promise<CronResult>;
-    updateJob(jobId: string, updates: Partial<{
-        prompt: string;
-        schedule: string;
-        name: string;
-        enabled: boolean;
-        repeat: number | null;
-        allowedTools: string[];
-    }>): Promise<CronResult>;
-    deleteJob(jobId: string): Promise<CronResult>;
-    pauseJob(jobId: string): Promise<CronResult>;
-    resumeJob(jobId: string): Promise<CronResult>;
-    triggerJob(jobId: string): Promise<CronResult>;
-    /** Validate cron schedule expression. Returns error or null. */
-    validateSchedule?(schedule: string): string | null;
-}
-export declare const MAX_CRON_JOBS = 50;
-export declare function createCronTool(deps: CronToolDeps): PortableTool<CronToolParams>;

package/dist/skills/tools/cron-tool.js

@@ -1,175 +0,0 @@
-// ============================================================
-// Cron Tool — scheduled task management (CRUD).
-// Reference: hermes-agent-main/tools/cronjob_tools.py
-// Category: system
-// ============================================================
-export const CRON_TOOL_NAME = "cron";
-export const CRON_TOOL_SCHEMA = {
-    type: "object",
-    properties: {
-        action: {
-            type: "string",
-            enum: ["create", "list", "get", "update", "delete", "pause", "resume", "trigger"],
-            description: "CRUD action: create/list/get/update/delete/pause/resume/trigger.",
-        },
-        jobId: {
-            type: "string",
-            description: "Job ID. Required for get/update/delete/pause/resume/trigger.",
-        },
-        prompt: {
-            type: "string",
-            description: "Task prompt to execute on schedule. Required for create.",
-        },
-        schedule: {
-            type: "string",
-            description: "Schedule expression. Supports:\n" +
-                "- Cron: '0 9 * * *' (every day at 9am)\n" +
-                "- Shorthand: '5m' (every 5 min), '1h' (hourly), '1d' (daily)\n" +
-                "Required for create.",
-        },
-        name: {
-            type: "string",
-            description: "Human-readable job name.",
-        },
-        repeat: {
-            type: "number",
-            description: "Number of times to repeat (null = infinite). Default: null.",
-        },
-        allowedTools: {
-            type: "array",
-            items: { type: "string" },
-            description: "Tools the scheduled task is allowed to use.",
-        },
-        enabled: {
-            type: "boolean",
-            description: "Whether the job is enabled (for update).",
-        },
-    },
-    required: ["action"],
-};
-export const MAX_CRON_JOBS = 50;
-export function createCronTool(deps) {
-    return {
-        name: CRON_TOOL_NAME,
-        label: "Cron",
-        description: "Manage scheduled tasks. Create recurring jobs with cron expressions or shorthand " +
-            "('5m', '1h', '0 9 * * *'). Jobs persist locally and survive restarts. " +
-            "Actions: create, list, get, update, delete, pause, resume, trigger (run now).",
-        parameters: CRON_TOOL_SCHEMA,
-        execute: async (_toolCallId, params) => {
-            switch (params.action) {
-                case "create": {
-                    if (!params.prompt) {
-                        return { content: [{ type: "text", text: "Error: prompt is required for create." }], details: { type: "cron", error: "missing_prompt" } };
-                    }
-                    if (!params.schedule) {
-                        return { content: [{ type: "text", text: "Error: schedule is required for create." }], details: { type: "cron", error: "missing_schedule" } };
-                    }
-                    if (deps.validateSchedule) {
-                        const err = deps.validateSchedule(params.schedule);
-                        if (err)
-                            return { content: [{ type: "text", text: `Error: invalid schedule — ${err}` }], details: { type: "cron", error: "invalid_schedule" } };
-                    }
-                    // Check max jobs limit
-                    const existing = await deps.listJobs();
-                    if (existing.jobs && existing.jobs.length >= MAX_CRON_JOBS) {
-                        return { content: [{ type: "text", text: `Error: maximum ${MAX_CRON_JOBS} jobs reached. Delete unused jobs first.` }], details: { type: "cron", error: "max_jobs_reached" } };
-                    }
-                    const r = await deps.createJob({ prompt: params.prompt, schedule: params.schedule, name: params.name, repeat: params.repeat, allowedTools: params.allowedTools });
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: formatJob(r.job) }], details: { type: "cron", action: "create", jobId: r.job.id } };
-                }
-                case "list": {
-                    const r = await deps.listJobs();
-                    if (!r.jobs || r.jobs.length === 0) {
-                        return { content: [{ type: "text", text: "No scheduled jobs." }], details: { type: "cron", action: "list", count: 0 } };
-                    }
-                    const lines = [`Scheduled jobs (${r.jobs.length}):`, ""];
-                    for (const j of r.jobs) {
-                        lines.push(`- **${j.name || j.id}** [${j.state}] ${j.scheduleDisplay} — next: ${j.nextRunAt || "N/A"}`);
-                    }
-                    return { content: [{ type: "text", text: lines.join("\n") }], details: { type: "cron", action: "list", count: r.jobs.length } };
-                }
-                case "get": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const r = await deps.getJob(params.jobId);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: formatJob(r.job) }], details: { type: "cron", action: "get", jobId: params.jobId } };
-                }
-                case "update": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const updates = {};
-                    if (params.prompt !== undefined)
-                        updates.prompt = params.prompt;
-                    if (params.schedule !== undefined)
-                        updates.schedule = params.schedule;
-                    if (params.name !== undefined)
-                        updates.name = params.name;
-                    if (params.enabled !== undefined)
-                        updates.enabled = params.enabled;
-                    if (params.repeat !== undefined)
-                        updates.repeat = params.repeat;
-                    if (params.allowedTools !== undefined)
-                        updates.allowedTools = params.allowedTools;
-                    const r = await deps.updateJob(params.jobId, updates);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: `Job updated.\n${formatJob(r.job)}` }], details: { type: "cron", action: "update", jobId: params.jobId } };
-                }
-                case "delete": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const r = await deps.deleteJob(params.jobId);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: `Job ${params.jobId} deleted.` }], details: { type: "cron", action: "delete", jobId: params.jobId } };
-                }
-                case "pause": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const r = await deps.pauseJob(params.jobId);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: `Job ${params.jobId} paused.` }], details: { type: "cron", action: "pause", jobId: params.jobId } };
-                }
-                case "resume": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const r = await deps.resumeJob(params.jobId);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: `Job ${params.jobId} resumed.` }], details: { type: "cron", action: "resume", jobId: params.jobId } };
-                }
-                case "trigger": {
-                    if (!params.jobId)
-                        return { content: [{ type: "text", text: "Error: jobId required." }], details: { type: "cron", error: "missing_jobId" } };
-                    const r = await deps.triggerJob(params.jobId);
-                    if (!r.success)
-                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "cron", error: r.error } };
-                    return { content: [{ type: "text", text: `Job ${params.jobId} triggered (running now).` }], details: { type: "cron", action: "trigger", jobId: params.jobId } };
-                }
-                default:
-                    return { content: [{ type: "text", text: `Error: unknown action "${params.action}".` }], details: { type: "cron", error: "unknown_action" } };
-            }
-        },
-    };
-}
-function formatJob(job) {
-    const lines = [
-        `Job: ${job.name || job.id}`,
-        `ID: ${job.id}`,
-        `Schedule: ${job.scheduleDisplay} (${job.schedule})`,
-        `State: ${job.state}`,
-        `Repeat: ${job.repeat.times === null ? "infinite" : `${job.repeat.completed}/${job.repeat.times}`}`,
-    ];
-    if (job.nextRunAt)
-        lines.push(`Next run: ${job.nextRunAt}`);
-    if (job.lastRunAt)
-        lines.push(`Last run: ${job.lastRunAt} (${job.lastStatus || "unknown"})`);
-    lines.push(`Prompt: ${job.prompt.slice(0, 100)}${job.prompt.length > 100 ? "..." : ""}`);
-    return lines.join("\n");
-}

package/dist/skills/tools/edit-tool.d.ts

@@ -1,43 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const EDIT_TOOL_NAME: "edit";
-export interface EditToolParams {
-    path: string;
-    oldText: string;
-    newText: string;
-}
-export declare const EDIT_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly path: {
-            readonly type: "string";
-            readonly description: "Path to the file to edit (relative or absolute).";
-        };
-        readonly oldText: {
-            readonly type: "string";
-            readonly description: "Exact text to find and replace (must match exactly, including whitespace).";
-        };
-        readonly newText: {
-            readonly type: "string";
-            readonly description: "New text to replace the old text with.";
-        };
-    };
-    readonly required: readonly ["path", "oldText", "newText"];
-};
-/** Deps injected by the host runtime for file editing. */
-export interface EditToolDeps {
-    /** Read file content as text. */
-    readFile(path: string): Promise<string>;
-    /** Write content back. */
-    writeFile(path: string, content: string): Promise<void>;
-    /** Resolve a relative path to absolute. */
-    resolvePath(input: string): string;
-    /**
-     * Check for concurrent modification before writing.
-     * The host tracks when each file was last read vs last modified on disk.
-     * Returns null if safe to write, or a descriptive warning if the file
-     * has been modified since last read (by user, another tool, or external process).
-     * If not provided, no concurrent modification check is performed.
-     */
-    checkConcurrentModification?(path: string): string | null;
-}
-export declare function createEditTool(deps: EditToolDeps): PortableTool<EditToolParams>;

package/dist/skills/tools/edit-tool.js

@@ -1,70 +0,0 @@
-// ============================================================
-// File Edit Tool — surgical text replacement in files.
-// Category: coding
-// ============================================================
-export const EDIT_TOOL_NAME = "edit";
-export const EDIT_TOOL_SCHEMA = {
-    type: "object",
-    properties: {
-        path: {
-            type: "string",
-            description: "Path to the file to edit (relative or absolute).",
-        },
-        oldText: {
-            type: "string",
-            description: "Exact text to find and replace (must match exactly, including whitespace).",
-        },
-        newText: {
-            type: "string",
-            description: "New text to replace the old text with.",
-        },
-    },
-    required: ["path", "oldText", "newText"],
-};
-export function createEditTool(deps) {
-    return {
-        name: EDIT_TOOL_NAME,
-        label: "Edit File",
-        description: "Edit a file by replacing exact text. The oldText must match exactly (including whitespace). " +
-            "Use this for precise, surgical edits. For multiple edits, call this tool multiple times.",
-        parameters: EDIT_TOOL_SCHEMA,
-        execute: async (_toolCallId, params) => {
-            const resolved = deps.resolvePath(params.path);
-            // Concurrent modification check
-            if (deps.checkConcurrentModification) {
-                const conflict = deps.checkConcurrentModification(resolved);
-                if (conflict) {
-                    return {
-                        content: [{ type: "text", text: `Concurrent modification detected: ${conflict}. Re-read the file first.` }],
-                        details: { type: "edit", path: resolved, success: false, reason: "concurrent_modification" },
-                    };
-                }
-            }
-            const content = await deps.readFile(resolved);
-            const index = content.indexOf(params.oldText);
-            if (index === -1) {
-                return {
-                    content: [{ type: "text", text: `Error: oldText not found in ${resolved}. Ensure it matches exactly.` }],
-                    details: { type: "edit", path: resolved, success: false, reason: "not_found" },
-                };
-            }
-            // Check for multiple matches
-            const secondIndex = content.indexOf(params.oldText, index + 1);
-            if (secondIndex !== -1) {
-                return {
-                    content: [{ type: "text", text: `Error: oldText matches multiple locations in ${resolved}. Include more context to make the match unique.` }],
-                    details: { type: "edit", path: resolved, success: false, reason: "ambiguous" },
-                };
-            }
-            const newContent = content.slice(0, index) + params.newText + content.slice(index + params.oldText.length);
-            await deps.writeFile(resolved, newContent);
-            // Compute first changed line
-            const preLines = content.slice(0, index).split("\n");
-            const firstChangedLine = preLines.length;
-            return {
-                content: [{ type: "text", text: `Edited ${resolved} (line ${firstChangedLine})` }],
-                details: { type: "edit", path: resolved, success: true, firstChangedLine },
-            };
-        },
-    };
-}

package/dist/skills/tools/exec-tool.d.ts

@@ -1,102 +0,0 @@
-import type { PortableTool } from "../portable-tool.js";
-export declare const EXEC_TOOL_NAME: "exec";
-export interface ExecToolParams {
-    command: string;
-    description?: string;
-    workdir?: string;
-    timeout?: number;
-    background?: boolean;
-}
-export declare const EXEC_TOOL_SCHEMA: {
-    readonly type: "object";
-    readonly properties: {
-        readonly command: {
-            readonly type: "string";
-            readonly description: "Shell command to execute. On Windows uses PowerShell, on Unix uses bash.";
-        };
-        readonly description: {
-            readonly type: "string";
-            readonly description: string;
-        };
-        readonly workdir: {
-            readonly type: "string";
-            readonly description: "Working directory for the command.";
-        };
-        readonly timeout: {
-            readonly type: "number";
-            readonly description: "Timeout in seconds (default: 120). Only applies to foreground commands.";
-        };
-        readonly background: {
-            readonly type: "boolean";
-            readonly description: string;
-        };
-    };
-    readonly required: readonly ["command"];
-};
-export interface ExecResult {
-    exitCode: number;
-    stdout: string;
-    stderr: string;
-    timedOut?: boolean;
-}
-export interface BackgroundExecResult {
-    pid: string;
-    started: boolean;
-    hint?: string;
-}
-/**
- * Deps injected by the host runtime for command execution.
- * The host is responsible for sandboxing, approval, path restrictions,
- * and security policies (dangerous command blocking).
- */
-export interface ExecToolDeps {
-    /**
-     * Execute a shell command in the foreground and return the result.
-     */
-    exec(command: string, options?: {
-        workdir?: string;
-        timeout?: number;
-    }): Promise<ExecResult>;
-    /**
-     * Start a background process and return its ID.
-     * The host manages the process lifecycle.
-     * If not provided, background=true will be rejected.
-     */
-    execBackground?(command: string, options?: {
-        workdir?: string;
-    }): Promise<BackgroundExecResult>;
-    /**
-     * Retrieve partial output from a background process.
-     * If not provided, background output queries are not supported.
-     */
-    getBackgroundOutput?(pid: string): Promise<{
-        stdout: string;
-        stderr: string;
-        running: boolean;
-    }>;
-    /**
-     * Validate a command before execution (skill-guard integration point).
-     * The host MUST implement this to block dangerous commands
-     * (rm -rf /, format, del /f /s /q, etc.).
-     * Returns null/undefined if allowed, or an error message string if blocked.
-     * If not provided, all commands are allowed (UNSAFE — only for tests).
-     */
-    validateCommand?(command: string): Promise<string | null | undefined>;
-    /**
-     * Persist large output to disk and return a reference URI.
-     * Called when stdout+stderr exceeds MAX_OUTPUT_CHARS.
-     * If provided, the tool returns a truncated preview + the persisted URI.
-     * This avoids flooding the LLM context with huge outputs.
-     */
-    persistOutput?(output: string, meta: {
-        command: string;
-        exitCode: number;
-    }): Promise<string>;
-    /**
-     * Interpret a non-zero exit code into a human-readable explanation.
-     * E.g. exit 127 → "command not found", exit 137 → "killed by SIGKILL (OOM?)".
-     * If not provided, raw exit code is shown.
-     */
-    interpretExitCode?(exitCode: number, stderr: string): string | undefined;
-}
-export declare function createExecTool(deps: ExecToolDeps): PortableTool<ExecToolParams>;