@ynhcj/xiaoyi-channel 0.0.207-beta → 0.0.209-beta

package/dist/src/tools/hmos-cli.js

@@ -0,0 +1,561 @@
+// HMOS CLI exec hook — CLI tool execution for HarmonyOS skills
+// Per exec-hmos.md §6: intercepts OpenClaw's built-in exec, validates against
+// CLI definitions from skill's references/clis/available_clis.json, and sends
+// FunctionExecute/ExecuteCLI to the device via WebSocket.
+//
+// ┌─────────────────────────────────────────────────────────────────────┐
+// │  §1  Types                                                         │
+// │  §2  Cache (globalThis singleton, mtime-based lazy refresh)         │
+// │  §3  Parser (tokenizer, argv validator, inputSchema enforcement)    │
+// │  §4  Executor (send ExecuteCLI, wait for ExecuteCLIRsp)             │
+// │  §5  Hook (before_tool_call registration)                           │
+// └─────────────────────────────────────────────────────────────────────┘
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { logger } from "../utils/logger.js";
+import { InvokeError, invokeErrorToResult } from "./invoke.js";
+import { getXYWebSocketManager } from "../client.js";
+import { sendCommand } from "../formatter.js";
+import { getCurrentTaskId } from "../task-manager.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// §2  Cache
+// ═══════════════════════════════════════════════════════════════════════════
+const DEFAULT_SKILL_ROOT = path.join(os.homedir(), ".openclaw", "workspace", "skills");
+const REFRESH_INTERVAL_MS = 30_000;
+const _g = globalThis;
+const CACHE_SLOT = "__xyCLICache";
+// ── Frontmatter helpers ──────────────────────────
+function parseSkillName(skillDir) {
+    const skillMdPath = path.join(skillDir, "SKILL.md");
+    let content;
+    try {
+        content = fs.readFileSync(skillMdPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    return extractNameFromFrontmatter(content);
+}
+function extractNameFromFrontmatter(content) {
+    if (content.charCodeAt(0) === 0xfeff)
+        content = content.slice(1);
+    const lines = content.split(/\r?\n/);
+    if (lines.length === 0 || lines[0].trim() !== "---")
+        return null;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            break;
+        const match = line.match(/^name:\s*(.+)$/);
+        if (match) {
+            let value = match[1].trim();
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            return value.length > 0 ? value : null;
+        }
+    }
+    return null;
+}
+export function extractCLINames(content) {
+    if (content.charCodeAt(0) === 0xfeff)
+        content = content.slice(1);
+    const lines = content.split(/\r?\n/);
+    if (lines.length === 0 || lines[0].trim() !== "---")
+        return null;
+    let inMetadata = false;
+    let inClis = false;
+    const cliNames = [];
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === "---")
+            break;
+        if (line.trim() === "metadata:") {
+            inMetadata = true;
+            continue;
+        }
+        if (!inMetadata)
+            continue;
+        if (line.trim() === "clis:") {
+            inClis = true;
+            continue;
+        }
+        if (!inClis)
+            continue;
+        const match = line.match(/^\s*-\s+name:\s*(.+)$/);
+        if (match) {
+            let value = match[1].trim();
+            if ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'"))) {
+                value = value.slice(1, -1);
+            }
+            if (value)
+                cliNames.push(value);
+        }
+        if (!line.trim().startsWith("-") && line.trim() !== "" && line[0] !== " " && line[0] !== "\t") {
+            inClis = false;
+        }
+    }
+    return cliNames.length > 0 ? cliNames : null;
+}
+// ── Scan & cache ─────────────────────────────────
+function scanCLIDirectories(rootDir) {
+    const skillClis = new Map();
+    if (!fs.existsSync(rootDir)) {
+        logger.log(`[CLI-CACHE] Skills root not found: ${rootDir}`);
+        return skillClis;
+    }
+    let skillDirs;
+    try {
+        skillDirs = fs.readdirSync(rootDir, { withFileTypes: true });
+    }
+    catch (err) {
+        logger.error(`[CLI-CACHE] Failed to read: ${rootDir}`, err);
+        return skillClis;
+    }
+    for (const dirent of skillDirs) {
+        if (!dirent.isDirectory() || dirent.name.startsWith("."))
+            continue;
+        const skillDir = path.join(rootDir, dirent.name);
+        const skillName = parseSkillName(skillDir);
+        if (!skillName)
+            continue;
+        const skillMdPath = path.join(skillDir, "SKILL.md");
+        let mdContent;
+        try {
+            mdContent = fs.readFileSync(skillMdPath, "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const declaredCLINames = extractCLINames(mdContent);
+        if (!declaredCLINames)
+            continue;
+        const clisJsonPath = path.join(skillDir, "references", "clis", "available_clis.json");
+        if (!fs.existsSync(clisJsonPath)) {
+            logger.warn(`[CLI-CACHE] Declared metadata.clis but missing ${clisJsonPath}`);
+            continue;
+        }
+        let cliDefs;
+        try {
+            const raw = JSON.parse(fs.readFileSync(clisJsonPath, "utf-8"));
+            if (!Array.isArray(raw)) {
+                logger.error(`[CLI-CACHE] ${clisJsonPath} is not an array`);
+                continue;
+            }
+            cliDefs = raw;
+        }
+        catch (err) {
+            logger.error(`[CLI-CACHE] Failed to parse: ${clisJsonPath}`, err);
+            continue;
+        }
+        const defMap = new Map();
+        for (const def of cliDefs) {
+            if (def.name)
+                defMap.set(def.name, def);
+        }
+        const entries = [];
+        for (const declaredName of declaredCLINames) {
+            const match = defMap.get(declaredName);
+            if (!match) {
+                logger.warn(`[CLI-CACHE] CLI '${declaredName}' declared in SKILL.md but missing from available_clis.json`);
+                continue;
+            }
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs.statSync(clisJsonPath).mtimeMs;
+            }
+            catch { /* ok */ }
+            entries.push({ cliName: declaredName, definition: match, filePath: clisJsonPath, mtimeMs });
+        }
+        if (entries.length > 0) {
+            skillClis.set(skillName, entries);
+            logger.log(`[CLI-CACHE] Skill '${skillName}': ${entries.length} CLI(s) cached`);
+        }
+    }
+    return skillClis;
+}
+function createCacheState(rootDir) {
+    const skillClis = scanCLIDirectories(rootDir);
+    let rootMtimeMs = 0;
+    try {
+        rootMtimeMs = fs.statSync(rootDir).mtimeMs;
+    }
+    catch { /* ok */ }
+    return { skillClis, lastScanMs: Date.now(), rootDir, rootMtimeMs };
+}
+function maybeRefresh(state) {
+    const now = Date.now();
+    if (now - state.lastScanMs < REFRESH_INTERVAL_MS)
+        return;
+    let currentMtime = 0;
+    try {
+        currentMtime = fs.statSync(state.rootDir).mtimeMs;
+    }
+    catch {
+        return;
+    }
+    if (currentMtime !== state.rootMtimeMs) {
+        logger.log("[CLI-CACHE] mtime changed, rescanning...");
+        state.skillClis = scanCLIDirectories(state.rootDir);
+        state.rootMtimeMs = currentMtime;
+    }
+    state.lastScanMs = now;
+}
+function wrapState(state) {
+    return {
+        getCLIs(skillName) { maybeRefresh(state); return state.skillClis.get(skillName) ?? null; },
+        getCLI(skillName, cliName) {
+            maybeRefresh(state);
+            const entries = state.skillClis.get(skillName);
+            if (!entries)
+                return null;
+            return entries.find(e => e.cliName === cliName) ?? null;
+        },
+        hasCLI(skillName, cliName) { return this.getCLI(skillName, cliName) !== null; },
+        async refresh() {
+            state.skillClis = scanCLIDirectories(state.rootDir);
+            state.lastScanMs = Date.now();
+            try {
+                state.rootMtimeMs = fs.statSync(state.rootDir).mtimeMs;
+            }
+            catch {
+                state.rootMtimeMs = 0;
+            }
+            logger.log(`[CLI-CACHE] Refreshed: ${state.skillClis.size} skills with CLIs`);
+        },
+        getRootDir() { return state.rootDir; },
+    };
+}
+export function getCLICache(rootDir) {
+    const dir = rootDir ?? DEFAULT_SKILL_ROOT;
+    const existing = _g[CACHE_SLOT];
+    if (existing && existing.rootDir === dir)
+        return wrapState(existing);
+    const state = createCacheState(dir);
+    _g[CACHE_SLOT] = state;
+    logger.log(`[CLI-CACHE] Init: ${state.skillClis.size} skills with CLIs from ${dir}`);
+    return wrapState(state);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// §3  Parser
+// ═══════════════════════════════════════════════════════════════════════════
+const DANGEROUS_PATTERNS = [
+    /[`]/,
+    /\$\(/,
+    /;/,
+    /\|/,
+    /&&/,
+    /\|\|/,
+    />/,
+    /</,
+    /\n/,
+];
+/** Tokenize a command string into argv, respecting single/double quotes. */
+function tokenizeCommand(command) {
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(command)) {
+            throw new InvokeError("CLI_COMMAND_BLOCKED", `Command contains dangerous shell syntax: ${pattern}`);
+        }
+    }
+    const tokens = [];
+    let current = "";
+    let inSingle = false;
+    let inDouble = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (ch === "'" && !inDouble) {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (ch === '"' && !inSingle) {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (/\s/.test(ch) && !inSingle && !inDouble) {
+            if (current.length > 0) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current.length > 0)
+        tokens.push(current);
+    if (inSingle || inDouble) {
+        throw new InvokeError("CLI_COMMAND_BLOCKED", "Unmatched quote in command");
+    }
+    return tokens;
+}
+/**
+ * Parse and validate a command string against a CLI definition.
+ * Returns typed ParsedCLIArgs ready for ExecuteCLI assembly.
+ */
+export function parseAndValidate(command, cliDef) {
+    const tokens = tokenizeCommand(command);
+    if (tokens.length === 0)
+        throw new InvokeError("CLI_COMMAND_BLOCKED", "Empty command");
+    // Match prefix against CLI name tokens
+    const cliNameTokens = cliDef.name.split(/\s+/);
+    if (tokens.length < cliNameTokens.length) {
+        throw new InvokeError("CLI_COMMAND_BLOCKED", `Command too short to match CLI prefix '${cliDef.name}'`);
+    }
+    for (let i = 0; i < cliNameTokens.length; i++) {
+        if (tokens[i] !== cliNameTokens[i]) {
+            throw new InvokeError("CLI_COMMAND_BLOCKED", `Expected '${cliNameTokens[i]}' at position ${i}, got '${tokens[i]}'`);
+        }
+    }
+    const toolName = cliNameTokens[0];
+    const subcommand = cliNameTokens.slice(1).join(" ");
+    // Parse --flag pairs from remaining tokens
+    const flagTokens = tokens.slice(cliNameTokens.length);
+    const schema = cliDef.inputSchema;
+    const parsedArgs = {};
+    const seenFlags = new Set();
+    for (let i = 0; i < flagTokens.length;) {
+        const token = flagTokens[i];
+        if (!token.startsWith("--")) {
+            throw new InvokeError("CLI_COMMAND_BLOCKED", `Unexpected token '${token}': only --flag format is allowed`);
+        }
+        const flagName = token.slice(2);
+        if (!schema?.properties || !(flagName in schema.properties)) {
+            throw new InvokeError("CLI_COMMAND_BLOCKED", `Unknown flag '--${flagName}' for CLI '${cliDef.name}'`);
+        }
+        const propDef = schema.properties[flagName];
+        // Duplicate flag handling — only allowed for array type
+        if (seenFlags.has(flagName) && propDef.type !== "array") {
+            throw new InvokeError("INVALID_PARAM", `Duplicate flag '--${flagName}' (only array-type flags allow repetition)`);
+        }
+        seenFlags.add(flagName);
+        // Boolean flag — presence means true, no value token
+        if (propDef.type === "boolean") {
+            parsedArgs[flagName] = true;
+            i++;
+            continue;
+        }
+        // String / number / array — must have a value token
+        i++;
+        if (i >= flagTokens.length) {
+            throw new InvokeError("INVALID_PARAM", `Flag '--${flagName}' requires a value`);
+        }
+        const rawValue = flagTokens[i];
+        if (propDef.type === "number") {
+            const numVal = Number(rawValue);
+            if (isNaN(numVal))
+                throw new InvokeError("INVALID_PARAM", `Flag '--${flagName}' expects a number, got '${rawValue}'`);
+            parsedArgs[flagName] = numVal;
+        }
+        else if (propDef.type === "string") {
+            parsedArgs[flagName] = rawValue;
+        }
+        else if (propDef.type === "array") {
+            if (!Array.isArray(parsedArgs[flagName])) {
+                parsedArgs[flagName] = [rawValue];
+            }
+            else {
+                parsedArgs[flagName].push(rawValue);
+            }
+        }
+        i++;
+    }
+    // Validate required params
+    if (schema?.required) {
+        for (const req of schema.required) {
+            if (!(req in parsedArgs)) {
+                throw new InvokeError("INVALID_PARAM", `Missing required flag '--${req}' for CLI '${cliDef.name}'`);
+            }
+        }
+    }
+    return { toolName, subcommand, args: parsedArgs };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// §4  Executor
+// ═══════════════════════════════════════════════════════════════════════════
+const EXECUTE_CLI_TIMEOUT_MS = 60_000;
+// CLI serial lock — separate from Device lock per spec §6.9
+const CLI_LOCKS_SLOT = "__xyCLILocks";
+if (!_g[CLI_LOCKS_SLOT])
+    _g[CLI_LOCKS_SLOT] = new Map();
+const cliLocks = _g[CLI_LOCKS_SLOT];
+function acquireCLILock(sessionId) {
+    return cliLocks.get(sessionId) ?? null;
+}
+function setCLILock(sessionId) {
+    let release;
+    const promise = new Promise((r) => { release = r; });
+    cliLocks.set(sessionId, promise);
+    return () => {
+        if (cliLocks.get(sessionId) === promise)
+            cliLocks.delete(sessionId);
+        release();
+    };
+}
+/**
+ * Execute a CLI command via WebSocket:
+ * 1. Acquire CLI serial lock (per session)
+ * 2. Send FunctionExecute/ExecuteCLI
+ * 3. Wait for FunctionExecute/ExecuteCLIRsp (via cli-response event)
+ * 4. Return result or error
+ */
+export async function executeCLI(parsed, sessionCtx, toolCallId) {
+    const { config, sessionId, taskId, messageId } = sessionCtx;
+    const log = (msg, ...args) => logger.withContext(sessionId, taskId).log(msg, ...args);
+    log("[CLI-EXEC] Sending ExecuteCLI", { toolCallId, toolName: parsed.toolName, subcommand: parsed.subcommand, argKeys: Object.keys(parsed.args) });
+    const prevLock = acquireCLILock(sessionId);
+    if (prevLock) {
+        log("[CLI-EXEC] waiting for previous CLI lock");
+        await prevLock;
+    }
+    const unlock = setCLILock(sessionId);
+    try {
+        return await new Promise((resolve, reject) => {
+            const wsManager = getXYWebSocketManager(config);
+            const timeout = setTimeout(() => {
+                wsManager.off("cli-response", handler);
+                const msg = `CLI '${parsed.toolName} ${parsed.subcommand}' timed out after 60s`;
+                log("[CLI-EXEC] timed out", msg);
+                reject(new InvokeError("TIMEOUT", msg));
+            }, EXECUTE_CLI_TIMEOUT_MS);
+            const handler = (rspPayload) => {
+                if (rspPayload.type !== "result") {
+                    log("[CLI-EXEC] skipping process event", { type: rspPayload.type });
+                    return;
+                }
+                clearTimeout(timeout);
+                wsManager.off("cli-response", handler);
+                if (rspPayload.status === "success") {
+                    const text = JSON.stringify(rspPayload.data ?? {});
+                    log("[CLI-EXEC] succeeded", { resultLength: text.length });
+                    resolve({ content: [{ type: "text", text }], details: rspPayload.data });
+                }
+                else {
+                    const errCode = rspPayload.errCode ?? "UNKNOWN";
+                    const errMsg = rspPayload.errMsg ?? "No error message";
+                    log("[CLI-EXEC] failed", { errCode, errMsg });
+                    reject(new InvokeError("UPSTREAM_ERROR", `CLI execution failed: ${errMsg}`, { errCode, errMsg, suggestion: rspPayload.suggestion, data: rspPayload.data }));
+                }
+            };
+            wsManager.on("cli-response", handler);
+            const command = {
+                header: { namespace: "FunctionExecute", name: "ExecuteCLI" },
+                payload: { toolName: parsed.toolName, subcommand: parsed.subcommand, args: parsed.args },
+            };
+            const currentTaskId = getCurrentTaskId(sessionId) ?? taskId;
+            sendCommand({ config, sessionId, taskId: currentTaskId, messageId, command, toolCallId }).catch((error) => {
+                clearTimeout(timeout);
+                wsManager.off("cli-response", handler);
+                log("[CLI-EXEC] sendCommand failed", { error: error instanceof Error ? error.message : String(error) });
+                reject(new InvokeError("NETWORK_ERROR", `Failed to send ExecuteCLI: ${error instanceof Error ? error.message : String(error)}`));
+            });
+        });
+    }
+    finally {
+        unlock();
+    }
+}
+export function cliErrorToResult(err) {
+    if (err instanceof InvokeError)
+        return invokeErrorToResult(err);
+    return invokeErrorToResult(new InvokeError("UNKNOWN", "Unexpected CLI execution error"));
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// §5  Hook
+// ═══════════════════════════════════════════════════════════════════════════
+export { parseSkillName as deriveSkillName };
+/**
+ * before_tool_call hook for CLI exec interception.
+ *
+ * Only handles built-in `exec` calls whose command prefix matches a CLI
+ * declared in the current skill's metadata.clis + available_clis.json.
+ * Non-matching commands return undefined (noop) so native exec handles them.
+ */
+export async function cliBeforeToolCallHandler(event, ctx) {
+    if (event.toolName !== "exec")
+        return undefined;
+    const rawCommand = event.params?.command;
+    if (typeof rawCommand !== "string" || rawCommand.trim().length === 0)
+        return undefined;
+    const t0 = performance.now();
+    const command = rawCommand.trim();
+    // Need a current skill context
+    const workspaceDir = ctx.workspaceDir;
+    if (!workspaceDir) {
+        logger.log(`[CLI-HOOK] no workspaceDir, noop (${(performance.now() - t0).toFixed(1)}ms)`);
+        return undefined;
+    }
+    const skillName = parseSkillName(workspaceDir);
+    if (!skillName) {
+        logger.log(`[CLI-HOOK] no skill name in ${workspaceDir}, noop (${(performance.now() - t0).toFixed(1)}ms)`);
+        return undefined;
+    }
+    const cache = getCLICache();
+    const skillCLIs = cache.getCLIs(skillName);
+    if (!skillCLIs || skillCLIs.length === 0) {
+        logger.log(`[CLI-HOOK] Skill '${skillName}' has no CLIs, noop (${(performance.now() - t0).toFixed(1)}ms)`);
+        return undefined;
+    }
+    // Match longest CLI name first
+    const sorted = [...skillCLIs].sort((a, b) => b.cliName.length - a.cliName.length);
+    let matchedCLI = null;
+    for (const entry of sorted) {
+        if (command === entry.cliName || command.startsWith(entry.cliName + " ")) {
+            matchedCLI = entry;
+            break;
+        }
+    }
+    if (!matchedCLI) {
+        logger.log(`[CLI-HOOK] No CLI match for command prefix, noop (${(performance.now() - t0).toFixed(1)}ms)`);
+        return undefined;
+    }
+    logger.log(`[CLI-HOOK] Matched CLI '${matchedCLI.cliName}' (${(performance.now() - t0).toFixed(1)}ms)`);
+    // Parse and validate
+    let parsed;
+    try {
+        parsed = parseAndValidate(command, matchedCLI.definition);
+    }
+    catch (err) {
+        if (err instanceof InvokeError) {
+            logger.warn(`[CLI-HOOK] Validation failed: ${err.code} - ${err.message} (${(performance.now() - t0).toFixed(1)}ms)`);
+            return { block: true, blockReason: cliErrorToResult(err).content[0]?.text ?? err.message };
+        }
+        throw err;
+    }
+    // requirePermissions → requireApproval
+    const permissions = matchedCLI.definition.requirePermissions;
+    if (permissions && permissions.length > 0) {
+        logger.log(`[CLI-HOOK] requireApproval needed, returning (${(performance.now() - t0).toFixed(1)}ms)`);
+        return {
+            requireApproval: {
+                title: `Execute CLI: ${matchedCLI.cliName}`,
+                description: `Requires permissions: ${permissions.join(", ")}. Args: ${JSON.stringify(parsed.args)}`,
+            },
+        };
+    }
+    // Get session context and execute
+    const sessionCtx = (await import("./session-manager.js")).getCurrentSessionContext();
+    if (!sessionCtx) {
+        logger.warn(`[CLI-HOOK] No session context, blocking (${(performance.now() - t0).toFixed(1)}ms)`);
+        return { block: true, blockReason: JSON.stringify({ code: "CONFIG_MISSING", message: "No active session context for CLI execution", retryable: false }) };
+    }
+    try {
+        const result = await executeCLI(parsed, sessionCtx, event.toolCallId);
+        logger.log(`[CLI-HOOK] CLI execution completed (${(performance.now() - t0).toFixed(1)}ms)`);
+        return { block: true, blockReason: result.content[0]?.text ?? "" };
+    }
+    catch (err) {
+        const errResult = cliErrorToResult(err);
+        logger.warn(`[CLI-HOOK] CLI execution failed (${(performance.now() - t0).toFixed(1)}ms)`);
+        return { block: true, blockReason: errResult.content[0]?.text ?? "CLI execution failed" };
+    }
+}
+/**
+ * Register the CLI hook on the OpenClaw plugin API.
+ * Call during `registrationMode === "full"` in the plugin entry point.
+ */
+export function registerCLIHook(api) {
+    api.on("before_tool_call", cliBeforeToolCallHandler);
+    logger.log("[CLI-HOOK] Registered before_tool_call hook for CLI exec");
+}

package/dist/src/tools/invoke.d.ts

@@ -0,0 +1,48 @@
+/**
+ * invoke meta-tool — single-file implementation.
+ *
+ * The `invoke` tool is the only tool the LLM sees for calling skill-defined
+ * tools.  It locates the real tool definition via (bundleName, toolName),
+ * dispatches to Cloud/MCP (PluginExecutor) or Device (A2A command), and
+ * returns the result.
+ *
+ * Protocol: invoke.md
+ *
+ * Sections:
+ *   1. Types
+ *   2. Errors
+ *   3. SKILL.md parser
+ *   4. Tool cache
+ *   5. Template renderer
+ *   6. Cloud executor (REST / SSE / Websocket)
+ *   7. Device executor
+ *   8. Invoke tool factory (public API)
+ */
+import type { ChannelAgentTool } from "openclaw/plugin-sdk";
+import type { SessionContext } from "./session-manager.js";
+export type InvokeErrorCode = "INVALID_PARAM" | "INVALID_TOOL_DEFINITION" | "CONFIG_MISSING" | "AUTH_FAIL" | "PERMISSION_DENIED" | "CLI_COMMAND_BLOCKED" | "RATE_LIMIT" | "TIMEOUT" | "TOOL_NOT_FOUND" | "TOOL_CONFLICT" | "UNSUPPORTED_PLUGIN_TYPE" | "UNSUPPORTED_PROTOCOL" | "DEVICE_TOOL_BLOCKED" | "UPSTREAM_ERROR" | "NETWORK_ERROR" | "UNKNOWN";
+interface ExecuteResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: unknown;
+    isError?: boolean;
+}
+export declare class InvokeError extends Error {
+    readonly name = "InvokeError";
+    readonly code: InvokeErrorCode;
+    readonly retryable: boolean;
+    readonly details?: Record<string, unknown>;
+    constructor(code: InvokeErrorCode, message: string, details?: Record<string, unknown>);
+    get status(): number;
+}
+export declare function invokeErrorToResult(error: InvokeError): ExecuteResult;
+/**
+ * Create the invoke meta-tool for the given session context.
+ *
+ * This is the ONLY exported function — the single integration point for
+ * create-all-tools.ts.
+ */
+export declare function createInvokeTool(ctx: SessionContext): ChannelAgentTool;
+export {};