qlogicagent 2.13.3 → 2.13.5

package/dist/skills/tools/file-management-tool.js

@@ -0,0 +1,166 @@
+// ============================================================
+// File Management Tool — upload / delete / query files via
+// provider Files API (Volcengine, Kimi / OpenAI-compat).
+//
+// Not all LLM providers support file APIs. The tool is gated
+// on availability at registration time.
+// Category: utility
+// ============================================================
+// ── Upload ───────────────────────────────────────────────────
+export const FILE_UPLOAD_TOOL_NAME = "file_upload";
+export const FILE_UPLOAD_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        file_path: {
+            type: "string",
+            description: "Absolute path to the local file to upload. " +
+                "Supported: images (jpg/png/webp/gif), audio (mp3/wav/m4a/ogg/flac), video (mp4/mov/avi). " +
+                "The file will be uploaded to the configured provider's Files API and a file ID or public URL will be returned.",
+        },
+        purpose: {
+            type: "string",
+            description: "Upload purpose hint: 'media_reference' (for image/video/audio generation), " +
+                "'user_data' (general). Default: 'media_reference'.",
+        },
+    },
+    required: ["file_path"],
+};
+export function createFileUploadTool(deps) {
+    return {
+        name: FILE_UPLOAD_TOOL_NAME,
+        label: "File Upload",
+        searchHint: "upload file material reference asset provider 素材 上传 参考图 上传文件",
+        description: "Upload a local file to the cloud provider's Files API. " +
+            "Returns a file ID (or public URL) that can be used as input for media generation tools " +
+            "(image_generate, video_generate, video_edit, etc.). " +
+            "Use this when the user provides a local file that needs to be referenced by URL in media tools. " +
+            "IMPORTANT: Only call this tool for files that actually need to be uploaded for media generation. " +
+            "Not all providers support file upload — tool availability depends on the configured provider.",
+        parameters: FILE_UPLOAD_TOOL_SCHEMA,
+        // Ships local file contents to an external provider Files API → data-carrying egress.
+        isEgress: true,
+        egressCarriesData: true,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.uploadFile({
+                filePath: params.file_path,
+                purpose: params.purpose,
+            });
+            const parts = [`Uploaded "${result.filename}" (${formatBytes(result.bytes)}) via ${result.provider}`];
+            if (result.url) {
+                parts.push(`URL: ${result.url}`);
+            }
+            parts.push(`File ID: ${result.fileId}`);
+            return {
+                content: [{ type: "text", text: parts.join("\n") }],
+                details: {
+                    type: "file_upload",
+                    fileId: result.fileId,
+                    url: result.url,
+                    filename: result.filename,
+                    bytes: result.bytes,
+                    provider: result.provider,
+                },
+            };
+        },
+    };
+}
+// ── Query / List ─────────────────────────────────────────────
+export const FILE_QUERY_TOOL_NAME = "file_query";
+export const FILE_QUERY_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        file_id: {
+            type: "string",
+            description: "Query a specific file by ID. If omitted, lists recent uploaded files.",
+        },
+        limit: {
+            type: "number",
+            description: "Max number of files to list when file_id is omitted. Default: 10, max: 100.",
+        },
+    },
+    required: [],
+};
+export function createFileQueryTool(deps) {
+    return {
+        name: FILE_QUERY_TOOL_NAME,
+        label: "File Query",
+        searchHint: "query list uploaded file material status 素材 查询 已上传",
+        description: "Query or list uploaded files from the provider's Files API. " +
+            "Use file_id to get info on a specific file, or omit to list recent uploads. " +
+            "Returns file ID, name, size, status, and URL (if available).",
+        parameters: FILE_QUERY_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            if (params.file_id) {
+                const info = await deps.queryFile({ fileId: params.file_id });
+                const lines = [
+                    `File: ${info.filename}`,
+                    `ID: ${info.id}`,
+                    `Size: ${formatBytes(info.bytes)}`,
+                    `Status: ${info.status}`,
+                ];
+                if (info.url)
+                    lines.push(`URL: ${info.url}`);
+                if (info.createdAt)
+                    lines.push(`Created: ${info.createdAt}`);
+                return {
+                    content: [{ type: "text", text: lines.join("\n") }],
+                    details: { type: "file_query", fileId: info.id },
+                };
+            }
+            const limit = Math.min(Math.max(params.limit ?? 10, 1), 100);
+            const files = await deps.listFiles({ limit });
+            if (files.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No uploaded files found." }],
+                    details: { type: "file_query", count: 0 },
+                };
+            }
+            const lines = [`Found ${files.length} file(s):\n`];
+            for (const f of files) {
+                lines.push(`- ${f.filename} | ID: ${f.id} | ${formatBytes(f.bytes)} | ${f.status}${f.url ? ` | ${f.url}` : ""}`);
+            }
+            return {
+                content: [{ type: "text", text: lines.join("\n") }],
+                details: { type: "file_query", count: files.length },
+            };
+        },
+    };
+}
+// ── Delete ───────────────────────────────────────────────────
+export const FILE_DELETE_TOOL_NAME = "file_delete";
+export const FILE_DELETE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        file_id: {
+            type: "string",
+            description: "ID of the uploaded file to delete.",
+        },
+    },
+    required: ["file_id"],
+};
+export function createFileDeleteTool(deps) {
+    return {
+        name: FILE_DELETE_TOOL_NAME,
+        label: "File Delete",
+        isDelete: true,
+        searchHint: "delete remove uploaded file material 素材 删除 清理上传",
+        description: "Delete a previously uploaded file from the provider's Files API. " +
+            "Use the file ID returned by file_upload or file_query.",
+        parameters: FILE_DELETE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            await deps.deleteFile({ fileId: params.file_id });
+            return {
+                content: [{ type: "text", text: `Deleted file ${params.file_id}` }],
+                details: { type: "file_delete", fileId: params.file_id },
+            };
+        },
+    };
+}
+// ── Helpers ──────────────────────────────────────────────────
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}

package/dist/skills/tools/image-generate-tool.d.ts

@@ -0,0 +1,74 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const IMAGE_GENERATE_TOOL_NAME: "image_generate";
+export interface ImageGenerateToolParams {
+    prompt: string;
+    purpose?: string;
+    style?: string;
+    size?: string;
+    image_url?: string;
+    n?: number;
+    quality?: string;
+    seed?: number;
+}
+export declare const IMAGE_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: "Image generation prompt. Enrich vague requests with style, lighting, composition, color, mood details.";
+        };
+        readonly purpose: {
+            readonly type: "string";
+            readonly description: "Intended use: 'social-media', 'short-video-cover', 'phone-wallpaper', 'avatar', 'poster', etc.";
+        };
+        readonly style: {
+            readonly type: "string";
+            readonly description: "Visual art style: 'photorealistic', 'anime', 'watercolor', 'oil-painting', '3d-render', etc.";
+        };
+        readonly size: {
+            readonly type: "string";
+            readonly description: "Dimensions: e.g. '1024x1792' (portrait), '1792x1024' (landscape), '1024x1024' (square). Default: '1024x1024'.";
+        };
+        readonly image_url: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly n: {
+            readonly type: "number";
+            readonly description: "Number of images to generate (1-4). Default: 1.";
+        };
+        readonly quality: {
+            readonly type: "string";
+            readonly description: "Image quality level: 'auto', 'high', 'low', 'hd'. Provider-specific.";
+        };
+        readonly seed: {
+            readonly type: "number";
+            readonly description: "Random seed for reproducible generation. Same seed + prompt = same result.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface ImageGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    size?: string;
+    durationMs?: number;
+}
+/** Deps injected by the host runtime for image generation. */
+export interface ImageGenerateToolDeps {
+    /**
+     * Generate images via the configured backend (relay, direct API, etc.).
+     * The host handles model selection, failover, watermark, and storage.
+     */
+    generateImage(params: {
+        prompt: string;
+        purpose?: string;
+        style?: string;
+        size?: string;
+        imageUrl?: string;
+        n?: number;
+        quality?: string;
+        seed?: number;
+    }): Promise<ImageGenerateResult>;
+}
+export declare function createImageGenerateTool(deps: ImageGenerateToolDeps): PortableTool<ImageGenerateToolParams>;

package/dist/skills/tools/image-generate-tool.js

@@ -0,0 +1,91 @@
+// ============================================================
+// Image Generate Tool — generate images via backend adapter.
+// Category: media
+// ============================================================
+export const IMAGE_GENERATE_TOOL_NAME = "image_generate";
+export const IMAGE_GENERATE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        prompt: {
+            type: "string",
+            description: "Image generation prompt. Enrich vague requests with style, lighting, composition, color, mood details.",
+        },
+        purpose: {
+            type: "string",
+            description: "Intended use: 'social-media', 'short-video-cover', 'phone-wallpaper', 'avatar', 'poster', etc.",
+        },
+        style: {
+            type: "string",
+            description: "Visual art style: 'photorealistic', 'anime', 'watercolor', 'oil-painting', '3d-render', etc.",
+        },
+        size: {
+            type: "string",
+            description: "Dimensions: e.g. '1024x1792' (portrait), '1792x1024' (landscape), '1024x1024' (square). Default: '1024x1024'.",
+        },
+        image_url: {
+            type: "string",
+            description: "Reference image URL for image-to-image generation (img2img). Character reference sheet or style transfer. " +
+                "MUST be a publicly accessible HTTP/HTTPS URL. Local file paths and data: URLs are NOT supported.",
+        },
+        n: {
+            type: "number",
+            description: "Number of images to generate (1-4). Default: 1.",
+        },
+        quality: {
+            type: "string",
+            description: "Image quality level: 'auto', 'high', 'low', 'hd'. Provider-specific.",
+        },
+        seed: {
+            type: "number",
+            description: "Random seed for reproducible generation. Same seed + prompt = same result.",
+        },
+    },
+    required: ["prompt"],
+};
+export function createImageGenerateTool(deps) {
+    return {
+        name: IMAGE_GENERATE_TOOL_NAME,
+        label: "Image Generate",
+        description: "Generate images from a text prompt. You MUST enrich vague prompts with details about style, lighting, " +
+            "composition, color, and mood before calling. Supports img2img via image_url reference. " +
+            "All generated images are saved locally and can be viewed immediately. " +
+            "IMPORTANT: For ordinary creative requests, infer reasonable defaults for purpose, style, and size and call this tool directly. " +
+            "Use ask_user only when a missing detail is critical or the request is genuinely ambiguous " +
+            "(e.g. the user asks for a production ad with unspecified brand constraints). " +
+            "Infer image size automatically from purpose (e.g. 1024x1792 for phone wallpaper, " +
+            "1792x1024 for landscape poster, 1024x1024 for avatar/social). Do NOT expose size as a raw number to the user. " +
+            "Do NOT invent Markdown image URLs, placeholder attachment paths, or claim an image was generated without this tool returning mediaUrls. " +
+            "ALL reference image URLs MUST be publicly accessible HTTP/HTTPS URLs. " +
+            "Use file_upload tool first if the user provides a local file. " +
+            "Local file paths and data: URIs are NOT supported by the generation API.",
+        parameters: IMAGE_GENERATE_TOOL_SCHEMA,
+        isEgress: true,
+        // 外发的是 prompt 文本 + 公开 HTTP 参考图 URL(本地文件须先 file_upload),不直接携带用户本地
+        // 隐私数据,故不触发 high_risk_egress 每次确认(team send / 文件上传等真外发仍保留确认)。
+        egressCarriesData: false,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.generateImage({
+                prompt: params.prompt,
+                purpose: params.purpose,
+                style: params.style,
+                size: params.size,
+                imageUrl: params.image_url,
+                n: params.n,
+                quality: params.quality,
+                seed: params.seed,
+            });
+            const count = result.mediaUrls.length;
+            const text = `Generated ${count} image${count > 1 ? "s" : ""}${result.model ? ` (model: ${result.model})` : ""}`;
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    type: "image_generate",
+                    model: result.model,
+                    size: result.size,
+                    durationMs: result.durationMs,
+                    mediaUrls: result.mediaUrls,
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,65 @@
+import type { PortableTool } from "../portable-tool.js";
+/** A single instruction file entry. */
+export interface InstructionFileInfo {
+    filename: string;
+    path: string;
+    size: number;
+    updatedAt: string;
+}
+/** Full instruction file (with content). */
+export interface InstructionFileContent extends InstructionFileInfo {
+    content: string;
+}
+/** Deps injected by the host runtime for instructions CRUD. */
+export interface InstructionsToolDeps {
+    /** List all instruction files for a project (recursive). */
+    list(projectId: string): InstructionFileInfo[];
+    /** Read a single instruction file. Returns null if not found. */
+    read(projectId: string, filename: string): InstructionFileContent | null;
+    /** Write (create or overwrite) an instruction file. */
+    write(projectId: string, filename: string, content: string): InstructionFileContent;
+    /** Remove an instruction file. Returns true if deleted. */
+    remove(projectId: string, filename: string): boolean;
+}
+export declare const INSTRUCTIONS_TOOL_NAME: "instructions";
+export type InstructionsAction = "list" | "read" | "write" | "edit" | "delete";
+export interface InstructionsToolParams {
+    action: InstructionsAction;
+    project_id: string;
+    filename?: string;
+    content?: string;
+    old_text?: string;
+    new_text?: string;
+}
+export declare const INSTRUCTIONS_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly action: {
+            readonly type: "string";
+            readonly enum: readonly ["list", "read", "write", "edit", "delete"];
+            readonly description: "Operation: list all files, read a file, write (create/overwrite), edit (partial replace), or delete a file.";
+        };
+        readonly project_id: {
+            readonly type: "string";
+            readonly description: "Project ID. Use \"default\" for the default project.";
+        };
+        readonly filename: {
+            readonly type: "string";
+            readonly description: "Instruction file name ending in .md (e.g. \"code-style.md\"). Required for read/write/delete. Sub-paths like \"testing/unit-test.md\" are supported.";
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly description: "Markdown content for the instruction file. Required for write action.";
+        };
+        readonly old_text: {
+            readonly type: "string";
+            readonly description: "Required for edit action: the exact existing text to find and replace (must appear exactly once).";
+        };
+        readonly new_text: {
+            readonly type: "string";
+            readonly description: "Required for edit action: the replacement text.";
+        };
+    };
+    readonly required: readonly ["action", "project_id"];
+};
+export declare function createInstructionsTool(deps: InstructionsToolDeps): PortableTool<InstructionsToolParams>;

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

@@ -0,0 +1,209 @@
+// ============================================================
+// Instructions Tool — unified CRUD for project instruction files (.md).
+//
+// Runtime-agnostic: the actual file I/O is injected via deps.
+// Gateway provides InstructionsModule; Hub provides HTTP client;
+// Electron provides IPC bridge.
+//
+// Merged from 4 separate tools (instructions_list/read/write/delete)
+// into a single tool with action enum — CC alignment (compact style).
+//
+// Category: project-management
+// ============================================================
+// ── Unified Instructions Tool ───────────────────────────────
+export const INSTRUCTIONS_TOOL_NAME = "instructions";
+export const INSTRUCTIONS_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["list", "read", "write", "edit", "delete"],
+            description: "Operation: list all files, read a file, write (create/overwrite), edit (partial replace), or delete a file.",
+        },
+        project_id: {
+            type: "string",
+            description: 'Project ID. Use "default" for the default project.',
+        },
+        filename: {
+            type: "string",
+            description: 'Instruction file name ending in .md (e.g. "code-style.md"). Required for read/write/delete. Sub-paths like "testing/unit-test.md" are supported.',
+        },
+        content: {
+            type: "string",
+            description: "Markdown content for the instruction file. Required for write action.",
+        },
+        old_text: {
+            type: "string",
+            description: "Required for edit action: the exact existing text to find and replace (must appear exactly once).",
+        },
+        new_text: {
+            type: "string",
+            description: "Required for edit action: the replacement text.",
+        },
+    },
+    required: ["action", "project_id"],
+};
+export function createInstructionsTool(deps) {
+    return {
+        name: INSTRUCTIONS_TOOL_NAME,
+        label: "Instructions",
+        description: "Manage project instruction files (.md) — list, read, write, edit, or delete. " +
+            "Instructions define agent behavior rules, coding standards, and project context.",
+        parameters: INSTRUCTIONS_TOOL_SCHEMA,
+        isReadOnly: false,
+        isConcurrencySafe: true,
+        searchHint: "instructions list read write edit delete rules coding standards behavior guidelines",
+        execute: async (_toolCallId, params) => {
+            switch (params.action) {
+                case "list": {
+                    const files = deps.list(params.project_id);
+                    if (files.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No instruction files found for this project." }],
+                            details: { projectId: params.project_id, count: 0 },
+                        };
+                    }
+                    const listing = files
+                        .map((f) => `- ${f.filename} (${f.size} bytes, updated ${f.updatedAt})`)
+                        .join("\n");
+                    return {
+                        content: [{ type: "text", text: `Found ${files.length} instruction file(s):\n${listing}` }],
+                        details: { projectId: params.project_id, count: files.length, files },
+                    };
+                }
+                case "read": {
+                    if (!params.filename) {
+                        return {
+                            content: [{ type: "text", text: "filename is required for read action" }],
+                            details: { error: "missing_filename" },
+                        };
+                    }
+                    const file = deps.read(params.project_id, params.filename);
+                    if (!file) {
+                        return {
+                            content: [{ type: "text", text: `Instruction file not found: ${params.filename}` }],
+                            details: { projectId: params.project_id, filename: params.filename, error: "not_found" },
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: file.content }],
+                        details: { projectId: params.project_id, filename: file.filename, size: file.size },
+                    };
+                }
+                case "write": {
+                    if (!params.filename) {
+                        return {
+                            content: [{ type: "text", text: "filename is required for write action" }],
+                            details: { error: "missing_filename" },
+                        };
+                    }
+                    if (params.content === undefined || params.content === null) {
+                        return {
+                            content: [{ type: "text", text: "content is required for write action" }],
+                            details: { error: "missing_content" },
+                        };
+                    }
+                    if (!params.filename.endsWith(".md")) {
+                        return {
+                            content: [{ type: "text", text: "Filename must end with .md" }],
+                            details: { error: "invalid_filename" },
+                        };
+                    }
+                    if (params.filename.includes("..")) {
+                        return {
+                            content: [{ type: "text", text: "Path traversal not allowed" }],
+                            details: { error: "path_traversal" },
+                        };
+                    }
+                    const written = deps.write(params.project_id, params.filename, params.content);
+                    return {
+                        content: [{ type: "text", text: `Instruction file written: ${written.filename} (${written.size} bytes)` }],
+                        details: { projectId: params.project_id, filename: written.filename, size: written.size },
+                    };
+                }
+                case "edit": {
+                    if (!params.filename) {
+                        return {
+                            content: [{ type: "text", text: "filename is required for edit action" }],
+                            details: { error: "missing_filename" },
+                        };
+                    }
+                    if (!params.old_text) {
+                        return {
+                            content: [{ type: "text", text: "old_text is required for edit action" }],
+                            details: { error: "missing_old_text" },
+                        };
+                    }
+                    if (params.new_text === undefined || params.new_text === null) {
+                        return {
+                            content: [{ type: "text", text: "new_text is required for edit action" }],
+                            details: { error: "missing_new_text" },
+                        };
+                    }
+                    if (params.filename.includes("..")) {
+                        return {
+                            content: [{ type: "text", text: "Path traversal not allowed" }],
+                            details: { error: "path_traversal" },
+                        };
+                    }
+                    const existing = deps.read(params.project_id, params.filename);
+                    if (!existing) {
+                        return {
+                            content: [{ type: "text", text: `Instruction file not found: ${params.filename}` }],
+                            details: { projectId: params.project_id, filename: params.filename, error: "not_found" },
+                        };
+                    }
+                    const occurrences = existing.content.split(params.old_text).length - 1;
+                    if (occurrences === 0) {
+                        return {
+                            content: [{ type: "text", text: "old_text not found in the file" }],
+                            details: { projectId: params.project_id, filename: params.filename, error: "old_text_not_found" },
+                        };
+                    }
+                    if (occurrences > 1) {
+                        return {
+                            content: [{ type: "text", text: `old_text matches ${occurrences} locations — must match exactly once. Add more surrounding context to make it unique.` }],
+                            details: { projectId: params.project_id, filename: params.filename, error: "ambiguous_match", occurrences },
+                        };
+                    }
+                    const updatedContent = existing.content.replace(params.old_text, params.new_text);
+                    const edited = deps.write(params.project_id, params.filename, updatedContent);
+                    return {
+                        content: [{ type: "text", text: `Instruction file edited: ${edited.filename} (${edited.size} bytes)` }],
+                        details: { projectId: params.project_id, filename: edited.filename, size: edited.size },
+                    };
+                }
+                case "delete": {
+                    if (!params.filename) {
+                        return {
+                            content: [{ type: "text", text: "filename is required for delete action" }],
+                            details: { error: "missing_filename" },
+                        };
+                    }
+                    if (params.filename.includes("..")) {
+                        return {
+                            content: [{ type: "text", text: "Path traversal not allowed" }],
+                            details: { error: "path_traversal" },
+                        };
+                    }
+                    const ok = deps.remove(params.project_id, params.filename);
+                    if (!ok) {
+                        return {
+                            content: [{ type: "text", text: `Instruction file not found: ${params.filename}` }],
+                            details: { projectId: params.project_id, filename: params.filename, error: "not_found" },
+                        };
+                    }
+                    return {
+                        content: [{ type: "text", text: `Instruction file deleted: ${params.filename}` }],
+                        details: { projectId: params.project_id, filename: params.filename },
+                    };
+                }
+                default:
+                    return {
+                        content: [{ type: "text", text: `Unknown action: ${params.action}. Use list, read, write, edit, or delete.` }],
+                        details: { error: "unknown_action" },
+                    };
+            }
+        },
+    };
+}