qlogicagent 2.13.4 → 2.13.5

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

@@ -0,0 +1,173 @@
+// ============================================================
+// Team Tool — create and manage multi-agent teams (Swarm).
+// Reference: claude-code-haha/src/tools/TeamCreateTool/TeamCreateTool.ts
+//            claude-code-haha/src/tools/TeamDeleteTool/TeamDeleteTool.ts
+// Category: system
+// ============================================================
+export const TEAM_TOOL_NAME = "team";
+export const TEAM_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        action: {
+            type: "string",
+            enum: ["create", "delete", "list", "status", "send"],
+            description: "Team action: create (new team), delete (disband), list (all teams), status (team details), send (message a member and collect the reply).",
+        },
+        teamName: {
+            type: "string",
+            description: "Team name. Required for create/delete/status.",
+        },
+        to: {
+            type: "string",
+            description: "Target member name, full member id, or '*' to broadcast to all live members. Required for send.",
+        },
+        message: {
+            type: "string",
+            description: "Message content to deliver to the member. Required for send.",
+        },
+        summary: {
+            type: "string",
+            description: "Optional short summary (for logging/routing). Used by send.",
+        },
+        description: {
+            type: "string",
+            description: "Team description/objective. Used for create.",
+        },
+        members: {
+            type: "array",
+            description: "Team members with roles and tool restrictions.",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Agent name/role identifier." },
+                    role: { type: "string", description: "Role description (e.g. 'frontend developer')." },
+                    tools: { type: "array", items: { type: "string" }, description: "Allowed tools for this member." },
+                },
+                required: ["name", "role"],
+            },
+        },
+    },
+    required: ["action"],
+};
+export function createTeamTool(deps) {
+    return {
+        name: TEAM_TOOL_NAME,
+        label: "Team",
+        description: "Manage multi-agent teams. Create teams of specialized agents, then coordinate them with " +
+            "action=\"send\" (message a member or '*' broadcast; replies come back synchronously). " +
+            "Each member has a role and optional tool restrictions. Use for complex tasks requiring parallel work.",
+        parameters: TEAM_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            switch (params.action) {
+                case "create": {
+                    if (!params.teamName) {
+                        return { content: [{ type: "text", text: "Error: teamName required for create." }], details: { type: "team", error: "missing_name" } };
+                    }
+                    const r = await deps.createTeam({ teamName: params.teamName, description: params.description, members: params.members });
+                    if (!r.success) {
+                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "team", error: r.error } };
+                    }
+                    const lines = [`Team "${r.team.name}" created.`, `Lead: ${r.team.leadId}`, `Members: ${r.team.members.length}`];
+                    for (const m of r.team.members) {
+                        lines.push(`  - ${m.name} (${m.role})`);
+                    }
+                    return { content: [{ type: "text", text: lines.join("\n") }], details: { type: "team", action: "create", teamName: r.team.name } };
+                }
+                case "delete": {
+                    if (!params.teamName) {
+                        return { content: [{ type: "text", text: "Error: teamName required for delete." }], details: { type: "team", error: "missing_name" } };
+                    }
+                    const r = await deps.deleteTeam(params.teamName);
+                    if (!r.success) {
+                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "team", error: r.error } };
+                    }
+                    return { content: [{ type: "text", text: `Team "${params.teamName}" disbanded.` }], details: { type: "team", action: "delete", teamName: params.teamName } };
+                }
+                case "list": {
+                    const r = await deps.listTeams();
+                    if (!r.teams || r.teams.length === 0) {
+                        return { content: [{ type: "text", text: "No active teams." }], details: { type: "team", action: "list", count: 0 } };
+                    }
+                    const lines = [`Active teams (${r.teams.length}):`, ""];
+                    for (const t of r.teams) {
+                        lines.push(`- **${t.name}**: ${t.description || "(no description)"} — ${t.members.length} members`);
+                    }
+                    return { content: [{ type: "text", text: lines.join("\n") }], details: { type: "team", action: "list", count: r.teams.length } };
+                }
+                case "send": {
+                    if (!params.to || params.to.trim().length === 0) {
+                        return { content: [{ type: "text", text: "Error: 'to' is required for send (member name or '*')." }], details: { type: "team", action: "send", error: "missing_target" } };
+                    }
+                    if (!params.message || params.message.trim().length === 0) {
+                        return { content: [{ type: "text", text: "Error: message is required for send." }], details: { type: "team", action: "send", error: "empty_message" } };
+                    }
+                    // Validate target exists (unless broadcast)
+                    if (params.to !== "*") {
+                        const teammates = deps.listTeammates();
+                        if (!teammates.includes(params.to)) {
+                            return {
+                                content: [{ type: "text", text: `Error: member "${params.to}" not found in team. Available: ${teammates.join(", ")}` }],
+                                details: { type: "team", action: "send", error: "target_not_found", available: teammates },
+                            };
+                        }
+                    }
+                    const r = await deps.sendMessage({
+                        to: params.to.trim(),
+                        message: params.message.trim(),
+                        summary: params.summary,
+                        senderId: deps.getSenderId(),
+                    });
+                    if (!r.success) {
+                        return { content: [{ type: "text", text: `Message delivery failed: ${r.error || "unknown error"}` }], details: { type: "team", action: "send", success: false, error: r.error } };
+                    }
+                    const target = params.to === "*" ? `broadcast (${r.recipients?.length || 0} recipients)` : params.to;
+                    // Replies come back synchronously — surface them so the sender can act on them.
+                    const replyText = r.replies?.length
+                        ? "\n\n" + r.replies.map((reply) => `${reply.name} replied:\n${reply.reply}`).join("\n\n")
+                        : "";
+                    return {
+                        content: [{ type: "text", text: `Message sent to ${target}.${replyText}` }],
+                        details: { type: "team", action: "send", success: true, to: params.to, recipients: r.recipients, replies: r.replies },
+                    };
+                }
+                case "status": {
+                    if (!params.teamName) {
+                        return { content: [{ type: "text", text: "Error: teamName required for status." }], details: { type: "team", error: "missing_name" } };
+                    }
+                    const r = await deps.getTeamStatus(params.teamName);
+                    if (!r.success) {
+                        return { content: [{ type: "text", text: `Error: ${r.error}` }], details: { type: "team", error: r.error } };
+                    }
+                    const t = r.team;
+                    const memberProg = r.memberProgress ?? {};
+                    const lines = [`Team: ${t.name}`, `Description: ${t.description || "—"}`, `Lead: ${t.leadId}`, `Created: ${t.createdAt}`, "", `Members (${t.members.length}):`];
+                    for (const m of t.members) {
+                        const tools = m.tools ? ` [tools: ${m.tools.join(", ")}]` : "";
+                        const workspace = m.worktreePath ? ` [worktree: ${m.worktreePath}]` : m.cwd ? ` [cwd: ${m.cwd}]` : "";
+                        const mp = memberProg[m.name];
+                        let statusStr = m.isActive === false ? " (idle)" : " (active)";
+                        if (mp) {
+                            const parts = [];
+                            if (mp.runningFor)
+                                parts.push(`running ${Math.round(mp.runningFor / 1000)}s`);
+                            if (mp.lastToolCall)
+                                parts.push(`tool: ${mp.lastToolCall}`);
+                            if (mp.idleFor !== undefined && mp.idleFor > 5)
+                                parts.push(`idle ${mp.idleFor}s`);
+                            if (mp.mediaProgress) {
+                                const pg = mp.mediaProgress;
+                                parts.push(`${pg.mediaType} ${pg.percent}% [${pg.status}] taskId=${pg.taskId}${pg.provider ? ` provider=${pg.provider}` : ""}`);
+                            }
+                            if (parts.length)
+                                statusStr = ` (${parts.join(", ")})`;
+                        }
+                        lines.push(`  - ${m.name} (${m.role})${tools}${workspace}${statusStr}`);
+                    }
+                    return { content: [{ type: "text", text: lines.join("\n") }], details: { type: "team", action: "status", teamName: t.name } };
+                }
+                default:
+                    return { content: [{ type: "text", text: `Error: unknown action "${params.action}".` }], details: { type: "team", error: "unknown_action" } };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const THREE_D_GENERATE_TOOL_NAME: "three_d_generate";
+export interface ThreeDGenerateToolParams {
+    prompt: string;
+    image_url?: string;
+    output_format?: string;
+    seed?: number;
+}
+export declare const THREE_D_GENERATE_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly image_url: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly output_format: {
+            readonly type: "string";
+            readonly description: "3D model output format: 'glb' (default), 'obj', 'usd', 'usdz'.";
+        };
+        readonly seed: {
+            readonly type: "number";
+            readonly description: "Random seed for reproducible generation.";
+        };
+    };
+    readonly required: readonly ["prompt"];
+};
+export interface ThreeDGenerateResult {
+    mediaUrls: string[];
+    model?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+/** Deps injected by the host runtime for 3D generation. */
+export interface ThreeDGenerateToolDeps {
+    generate3D(params: {
+        prompt: string;
+        imageUrl?: string;
+        outputFormat?: string;
+        seed?: number;
+    }): Promise<ThreeDGenerateResult>;
+}
+export declare function createThreeDGenerateTool(deps: ThreeDGenerateToolDeps): PortableTool<ThreeDGenerateToolParams>;

package/dist/skills/tools/three-d-generate-tool.js

@@ -0,0 +1,66 @@
+// ============================================================
+// 3D Generate Tool — generate 3D models via backend adapter.
+// Category: media
+// ============================================================
+export const THREE_D_GENERATE_TOOL_NAME = "three_d_generate";
+export const THREE_D_GENERATE_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        prompt: {
+            type: "string",
+            description: "3D model generation prompt. Describe the object's shape, material, texture, color, and pose. " +
+                "For text-to-3D, provide a detailed description. For image-to-3D, also provide image_url.",
+        },
+        image_url: {
+            type: "string",
+            description: "Reference image URL for image-to-3D generation. The image should show the object clearly " +
+                "from a single viewpoint with clean background for best results. " +
+                "MUST be a publicly accessible HTTP/HTTPS URL. Local file paths and data: URLs are NOT supported.",
+        },
+        output_format: {
+            type: "string",
+            description: "3D model output format: 'glb' (default), 'obj', 'usd', 'usdz'.",
+        },
+        seed: {
+            type: "number",
+            description: "Random seed for reproducible generation.",
+        },
+    },
+    required: ["prompt"],
+};
+export function createThreeDGenerateTool(deps) {
+    return {
+        name: THREE_D_GENERATE_TOOL_NAME,
+        label: "3D Generate",
+        searchHint: "3d model generate asset glb obj 三维 3D模型 建模 三维模型",
+        description: "Generate a 3D model from a text prompt or reference image. " +
+            "Supports text-to-3D and image-to-3D workflows. Output formats include GLB, OBJ, USD. " +
+            "The generated model can be viewed in any 3D viewer or imported into game engines. " +
+            "IMPORTANT: Describe the object in detail — shape, size, material, texture, color, and pose.",
+        parameters: THREE_D_GENERATE_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.generate3D({
+                prompt: params.prompt,
+                imageUrl: params.image_url,
+                outputFormat: params.output_format,
+                seed: params.seed,
+            });
+            const count = result.mediaUrls.length;
+            let text = `Generated ${count} 3D model${count > 1 ? "s" : ""}${result.model ? ` (model: ${result.model})` : ""}`;
+            // Surface debug metadata when no URLs found
+            if (count === 0 && result.metadata?.debugResponseKeys) {
+                text += ` [debug: response keys=${JSON.stringify(result.metadata.debugResponseKeys)}, content=${result.metadata.debugContentSample ?? "null"}]`;
+            }
+            return {
+                content: [{ type: "text", text }],
+                details: {
+                    type: "three_d_generate",
+                    model: result.model,
+                    durationMs: result.durationMs,
+                    mediaUrls: result.mediaUrls,
+                    ...(result.metadata ?? {}),
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,62 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TOOL_SEARCH_TOOL_NAME: "tool_search";
+export interface ToolSearchToolParams {
+    query: string;
+    maxResults?: number;
+}
+export declare const TOOL_SEARCH_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly query: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly maxResults: {
+            readonly type: "number";
+            readonly description: "Maximum number of results to return (default: 5).";
+        };
+    };
+    readonly required: readonly ["query"];
+};
+export interface DeferredToolInfo {
+    name: string;
+    description: string;
+    /** Optional search hint for better discovery */
+    searchHint?: string;
+}
+export interface ToolSearchOutput {
+    matches: DeferredToolInfo[];
+    query: string;
+    totalDeferred: number;
+}
+/**
+ * Host-provided deferred tool registry.
+ * The host manages which tools are loaded vs deferred,
+ * and handles activation when selected.
+ */
+export interface ToolSearchToolDeps {
+    /**
+     * Search deferred tools by query.
+     * Supports "select:name" for direct activation and keyword search.
+     */
+    searchTools(query: string, options?: {
+        maxResults?: number;
+    }): Promise<ToolSearchOutput>;
+    /**
+     * Activate a deferred tool so it appears in subsequent turns.
+     * Returns true if activation succeeded.
+     */
+    activateTool?(name: string): Promise<boolean>;
+}
+export interface ToolSearchCorpusEntry {
+    name: string;
+    description: string;
+    searchHint?: string;
+}
+/**
+ * Score a keyword query against a tool corpus (CC-aligned weights).
+ * Query syntax: plain terms rank, "+term" is required (must appear in
+ * name/description/searchHint). CJK terms match by substring.
+ */
+export declare function searchToolCorpus(entries: ToolSearchCorpusEntry[], query: string, maxResults: number): ToolSearchOutput;
+export declare function createToolSearchTool(deps: ToolSearchToolDeps): PortableTool<ToolSearchToolParams>;

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

@@ -0,0 +1,187 @@
+// ============================================================
+// Tool Search Tool — discover deferred/hidden tools by keyword.
+// Reference: claude-code-haha/src/tools/ToolSearchTool/ToolSearchTool.ts
+// Category: system
+// ============================================================
+export const TOOL_SEARCH_TOOL_NAME = "tool_search";
+export const TOOL_SEARCH_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        query: {
+            type: "string",
+            description: 'Search query for tools. Use "select:toolName" to directly activate a deferred tool, ' +
+                "or provide keywords to search tool names/descriptions. " +
+                'Prefix a term with "+" to mark it as required (all +terms must match).',
+        },
+        maxResults: {
+            type: "number",
+            description: "Maximum number of results to return (default: 5).",
+        },
+    },
+    required: ["query"],
+};
+const DEFAULT_MAX_RESULTS = 5;
+const NON_ASCII_RE = /[^\x20-\x7E]/;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Word-prefix match for ASCII terms; plain substring for CJK/non-ASCII terms.
+ * JS `\b` only exists between \w and non-\w, so `\b视频` NEVER matches —
+ * CJK terms must use includes(). Escaping also fixes regex metachars ("c++").
+ */
+function termMatches(haystack, term) {
+    if (!haystack)
+        return false;
+    if (NON_ASCII_RE.test(term))
+        return haystack.includes(term);
+    return new RegExp(`\\b${escapeRegExp(term)}`, "i").test(haystack);
+}
+/** CamelCase/snake_case name splitter (CC parity). */
+function parseToolName(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/_/g, " ")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+/**
+ * Score a keyword query against a tool corpus (CC-aligned weights).
+ * Query syntax: plain terms rank, "+term" is required (must appear in
+ * name/description/searchHint). CJK terms match by substring.
+ */
+export function searchToolCorpus(entries, query, maxResults) {
+    const rawTerms = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const requiredTerms = [];
+    const optionalTerms = [];
+    for (const t of rawTerms) {
+        if (t.startsWith("+") && t.length > 1)
+            requiredTerms.push(t.slice(1));
+        else
+            optionalTerms.push(t);
+    }
+    const allTerms = [...requiredTerms, ...optionalTerms];
+    const scored = entries.map((entry) => {
+        const nameParts = parseToolName(entry.name);
+        const description = (entry.description ?? "").toLowerCase();
+        const searchHint = (entry.searchHint ?? "").toLowerCase();
+        if (requiredTerms.length > 0) {
+            const haystack = `${nameParts.join(" ")} ${description} ${searchHint}`;
+            if (!requiredTerms.every((rt) => haystack.includes(rt)))
+                return null;
+        }
+        let score = 0;
+        for (const term of allTerms) {
+            let termScore = 0;
+            // 1. Exact part match (highest)
+            if (nameParts.some((p) => p === term))
+                termScore = 10;
+            // 2. Substring within a part
+            else if (nameParts.some((p) => p.includes(term)))
+                termScore = 5;
+            // 3. Full name fallback
+            else if (entry.name.toLowerCase().includes(term))
+                termScore = 3;
+            // 4. SearchHint match (CJK-safe)
+            if (termMatches(searchHint, term))
+                termScore += 4;
+            // 5. Description match (CJK-safe)
+            if (termMatches(description, term))
+                termScore += 2;
+            score += termScore;
+        }
+        return { name: entry.name, description: entry.description, searchHint: entry.searchHint, score };
+    });
+    const matches = scored
+        .filter((m) => m !== null && m.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+    return { matches, query, totalDeferred: entries.length };
+}
+export function createToolSearchTool(deps) {
+    return {
+        name: TOOL_SEARCH_TOOL_NAME,
+        label: "Tool Search",
+        description: "Search and activate deferred tools (capabilities that exist but are not in your current tool list — see the deferred tool index in your system prompt). " +
+            'Use "select:toolName" to activate one directly (preferred when you know the name), ' +
+            "or search with ENGLISH keywords (e.g. \"video generate\"). " +
+            "Activated tools become callable from your next message.",
+        parameters: TOOL_SEARCH_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            if (!params.query || params.query.trim().length === 0) {
+                return {
+                    content: [{ type: "text", text: "Error: query is required." }],
+                    details: { type: "tool_search", error: "empty_query" },
+                };
+            }
+            const query = params.query.trim();
+            const maxResults = params.maxResults ?? DEFAULT_MAX_RESULTS;
+            // Handle direct selection: "select:toolName" or "select:A,B,C"
+            if (query.startsWith("select:")) {
+                const names = query.slice(7).split(",").map((n) => n.trim()).filter(Boolean);
+                const activated = [];
+                const notFound = [];
+                if (deps.activateTool) {
+                    for (const name of names) {
+                        const ok = await deps.activateTool(name);
+                        if (ok)
+                            activated.push(name);
+                        else
+                            notFound.push(name);
+                    }
+                }
+                else {
+                    // No activation support — just search
+                    const result = await deps.searchTools(query, { maxResults });
+                    return formatSearchResult(result);
+                }
+                const parts = [];
+                if (activated.length > 0) {
+                    parts.push(`Activated: ${activated.join(", ")}. These tools are now available.`);
+                }
+                if (notFound.length > 0) {
+                    parts.push(`Not found: ${notFound.join(", ")}.`);
+                }
+                return {
+                    content: [{ type: "text", text: parts.join("\n") }],
+                    details: { type: "tool_search", activated, notFound, mode: "select" },
+                };
+            }
+            // Keyword search
+            const result = await deps.searchTools(query, { maxResults });
+            return formatSearchResult(result);
+        },
+    };
+}
+function formatSearchResult(result) {
+    if (result.matches.length === 0) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `No tools found matching "${result.query}". ` +
+                        `Total deferred tools available: ${result.totalDeferred}.`,
+                }],
+            details: { type: "tool_search", query: result.query, matchCount: 0, totalDeferred: result.totalDeferred },
+        };
+    }
+    const lines = [
+        `Found ${result.matches.length} tool(s) matching "${result.query}" (${result.totalDeferred} total deferred):`,
+        "",
+    ];
+    for (const tool of result.matches) {
+        lines.push(`- **${tool.name}**: ${tool.description}`);
+    }
+    lines.push("");
+    lines.push('Use "select:toolName" to activate a tool for use in subsequent messages.');
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: {
+            type: "tool_search",
+            query: result.query,
+            matchCount: result.matches.length,
+            totalDeferred: result.totalDeferred,
+            matches: result.matches.map((m) => m.name),
+        },
+    };
+}

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

@@ -0,0 +1,50 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const TTS_TOOL_NAME: "tts";
+export interface TtsToolParams {
+    text: string;
+    channel?: string;
+    voice?: string;
+    speed?: number;
+}
+export declare const TTS_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly text: {
+            readonly type: "string";
+            readonly description: "Text to convert to speech.";
+        };
+        readonly channel: {
+            readonly type: "string";
+            readonly description: "Optional channel id to pick output format (e.g. telegram).";
+        };
+        readonly voice: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly speed: {
+            readonly type: "number";
+            readonly description: "Speech speed multiplier (0.25-4.0). Default is 1.0.";
+        };
+    };
+    readonly required: readonly ["text"];
+};
+export interface TtsResult {
+    audioPath: string;
+    provider?: string;
+    voiceCompatible?: boolean;
+    mediaUrls: string[];
+}
+/** Deps injected by the host runtime for TTS. */
+export interface TtsToolDeps {
+    /**
+     * Convert text to speech via the configured backend.
+     * The host handles voice selection, format conversion, and storage.
+     */
+    textToSpeech(params: {
+        text: string;
+        channel?: string;
+        voice?: string;
+        speed?: number;
+    }): Promise<TtsResult>;
+}
+export declare function createTtsTool(deps: TtsToolDeps): PortableTool<TtsToolParams>;

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

@@ -0,0 +1,58 @@
+// ============================================================
+// TTS Tool — text-to-speech via backend adapter.
+// Category: media
+// ============================================================
+export const TTS_TOOL_NAME = "tts";
+export const TTS_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        text: {
+            type: "string",
+            description: "Text to convert to speech.",
+        },
+        channel: {
+            type: "string",
+            description: "Optional channel id to pick output format (e.g. telegram).",
+        },
+        voice: {
+            type: "string",
+            description: "Voice name for TTS. Available voices depend on the provider. " +
+                "Common options: alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, shimmer.",
+        },
+        speed: {
+            type: "number",
+            description: "Speech speed multiplier (0.25-4.0). Default is 1.0.",
+        },
+    },
+    required: ["text"],
+};
+export function createTtsTool(deps) {
+    return {
+        name: TTS_TOOL_NAME,
+        label: "TTS",
+        shouldDefer: true,
+        searchHint: "tts text-to-speech speak voice narration read-aloud 语音 配音 朗读 文字转语音 语音合成 念出来",
+        description: "Convert text to speech (TTS) — read text aloud as spoken audio. " +
+            "Use for narration, voice messages, or any spoken-word output. " +
+            "DO NOT use for music, songs, or melodies — use music_generate instead.",
+        parameters: TTS_TOOL_SCHEMA,
+        execute: async (_toolCallId, params) => {
+            const result = await deps.textToSpeech({
+                text: params.text,
+                channel: params.channel,
+                voice: params.voice,
+                speed: params.speed,
+            });
+            return {
+                content: [{ type: "text", text: "已成功生成语音。" }],
+                details: {
+                    type: "tts",
+                    audioPath: result.audioPath,
+                    provider: result.provider,
+                    voiceCompatible: result.voiceCompatible,
+                    mediaUrls: result.mediaUrls,
+                },
+            };
+        },
+    };
+}