@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/tool-system/builtin/task.js

@@ -0,0 +1,139 @@
+/**
+ * Built-in task management — a single TodoWrite tool, cc-style.
+ *
+ * Design (2026-05-24 simplification, replacing the legacy 6-tool API):
+ *
+ *   - One tool, one shape: TodoWrite({ todos: [{content, status, activeForm}] }).
+ *     Each call replaces the entire snapshot — no per-item update API.
+ *   - The transcript IS the task store. The LLM reads its own last
+ *     TodoWrite tool_use input to know "where am I in the list".
+ *   - No module singleton. No in-memory map. No file persistence.
+ *     Resume hydrates by scanning the loaded transcript for the most
+ *     recent TodoWrite tool_use.
+ *   - Sub-agent isolation: when called from a spawned sub-agent, the
+ *     emitted task_update event carries the sub-agent's id so the UI
+ *     can keep the main and sub-agent todo lists separate (cc bucketing
+ *     by `context.agentId ?? sessionId`).
+ *
+ * Why no TaskManager:
+ *   The legacy TaskCreate/Update/Stop/Get/Output/List sextet stored
+ *   state behind a module-level TaskManager singleton. Desktop spawns
+ *   one worker process per agent/run, so the singleton vanished after
+ *   each run — the next run's `TaskList` returned "No tasks" even
+ *   though the transcript still had the full plan. Replacing the
+ *   sextet with one snapshot tool whose output lives in the transcript
+ *   makes the worker's lifecycle irrelevant: every restart re-reads
+ *   the snapshot for free.
+ */
+// ─── Tool definition ─────────────────────────────────────────────
+export const todoWriteToolDef = {
+    name: "TodoWrite",
+    description: "Manage the session todo list. Pass the COMPLETE list each call — there's no per-item update API, you rewrite the entire snapshot. " +
+        "Use proactively for tasks with 3+ steps. Exactly one item should be in_progress at a time. " +
+        "Always provide both `content` (imperative) and `activeForm` (present continuous) so the UI can show what's happening right now.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "The updated todo list. Replaces any previous list.",
+                items: {
+                    type: "object",
+                    properties: {
+                        content: {
+                            type: "string",
+                            description: "Imperative form, e.g. 'Run tests'.",
+                        },
+                        status: {
+                            type: "string",
+                            enum: ["pending", "in_progress", "completed"],
+                        },
+                        activeForm: {
+                            type: "string",
+                            description: "Present continuous form, e.g. 'Running tests'.",
+                        },
+                    },
+                    required: ["content", "status", "activeForm"],
+                },
+            },
+        },
+        required: ["todos"],
+    },
+};
+// ─── Tool implementation ─────────────────────────────────────────
+export async function todoWriteTool(args, ctx) {
+    const raw = args.todos;
+    if (!Array.isArray(raw)) {
+        return "Error: `todos` must be an array.";
+    }
+    const todos = parseTodos(raw);
+    // cc's "everything done → clear the panel" behaviour: when the last
+    // item flips to completed, drop the list so the UI doesn't keep
+    // showing a stale "all done" panel. The model can still see its
+    // history in the transcript if it needs to reference what was done.
+    const allDone = todos.length > 0 && todos.every((t) => t.status === "completed");
+    const effective = allDone ? [] : todos;
+    emitTaskUpdate(ctx, toTaskInfos(effective));
+    // Short, cc-style confirmation. The model already has the new snapshot
+    // in its own input — no point echoing the full list back here.
+    return "Todos have been updated. Continue to use TodoWrite to track progress.";
+}
+function parseTodos(raw) {
+    const out = [];
+    for (const r of raw) {
+        if (!r || typeof r !== "object")
+            continue;
+        const obj = r;
+        if (typeof obj.content !== "string")
+            continue;
+        const status = obj.status;
+        if (status !== "pending" && status !== "in_progress" && status !== "completed")
+            continue;
+        const activeForm = typeof obj.activeForm === "string" ? obj.activeForm : obj.content;
+        out.push({ content: obj.content, status, activeForm });
+    }
+    return out;
+}
+function toTaskInfos(todos) {
+    // Position-based ids — stable React keys for the UI; LLMs never see them.
+    return todos.map((t, i) => ({
+        id: String(i + 1),
+        subject: t.content,
+        activeForm: t.activeForm,
+        status: t.status,
+    }));
+}
+function emitTaskUpdate(ctx, tasks) {
+    const cb = ctx?.streamCallback;
+    cb?.({ type: "task_update", tasks });
+}
+// ─── Transcript replay (used by Engine on session resume) ────────
+/**
+ * Pull the latest todo snapshot from a transcript's event stream.
+ *
+ * Walks newest-first looking for a `tool_use` event whose toolName is
+ * TodoWrite — its args carry the canonical snapshot. Returns null if
+ * no TodoWrite call exists in the transcript (e.g. fresh session, or
+ * a session where the agent never used the tool).
+ */
+export function readLastTodoSnapshot(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        if (e.type !== "tool_use")
+            continue;
+        const d = e.data ?? {};
+        if (d.toolName !== "TodoWrite")
+            continue;
+        const args = (d.args ?? {});
+        const todos = args.todos;
+        if (!Array.isArray(todos))
+            continue;
+        const parsed = parseTodos(todos);
+        // Honour the same "all done → clear" rule as the live tool, so a
+        // session that finished with everything completed restores to an
+        // empty pinned panel.
+        const allDone = parsed.length > 0 && parsed.every((t) => t.status === "completed");
+        return allDone ? [] : toTaskInfos(parsed);
+    }
+    return null;
+}

package/dist/tool-system/builtin/tool-search.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Built-in ToolSearch tool — deferred tool schema discovery.
+ *
+ * MCP tools are initially registered with name-only (deferred).
+ * The model uses ToolSearch to discover full schemas on demand,
+ * saving context by not loading all MCP tool schemas upfront.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const toolSearchToolDef: ToolDefinition;
+export declare function toolSearchTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/tool-search.js

@@ -0,0 +1,90 @@
+/**
+ * Built-in ToolSearch tool — deferred tool schema discovery.
+ *
+ * MCP tools are initially registered with name-only (deferred).
+ * The model uses ToolSearch to discover full schemas on demand,
+ * saving context by not loading all MCP tool schemas upfront.
+ */
+export const toolSearchToolDef = {
+    name: "ToolSearch",
+    description: "Search for and discover available tools by name or keyword. " +
+        "Some tools (especially from MCP servers) are deferred — their full schemas " +
+        "are only loaded when you search for them. Use this to find the right tool.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: 'Query to find tools. Use "select:ToolName" for exact match, or keywords to search.',
+            },
+            max_results: {
+                type: "number",
+                description: "Maximum results to return (default: 5)",
+            },
+        },
+        required: ["query"],
+    },
+};
+export async function toolSearchTool(args, ctx) {
+    const query = args.query;
+    if (!query)
+        return "Error: query is required";
+    if (!ctx?.toolRegistry)
+        return "Error: ToolSearch is not configured (no registry in ctx)";
+    const maxResults = Math.min(args.max_results || 5, 20);
+    // "select:Name1,Name2" → exact match
+    if (query.startsWith("select:")) {
+        const names = query.slice(7).split(",").map((n) => n.trim());
+        return matchExact(ctx.toolRegistry, names);
+    }
+    // Keyword search
+    return searchByKeyword(ctx.toolRegistry, query, maxResults);
+}
+function matchExact(registry, names) {
+    const results = [];
+    for (const name of names) {
+        const tool = registry.getTool(name);
+        if (tool) {
+            results.push(formatTool(tool));
+        }
+        else {
+            results.push(`Tool "${name}" not found.`);
+        }
+    }
+    return results.join("\n\n---\n\n");
+}
+function searchByKeyword(registry, query, maxResults) {
+    const allTools = registry.listToolsDetailed();
+    const queryLower = query.toLowerCase();
+    const keywords = queryLower.split(/\s+/);
+    // Score each tool
+    const scored = allTools.map((tool) => {
+        let score = 0;
+        const nameLower = tool.name.toLowerCase();
+        const descLower = tool.description.toLowerCase();
+        for (const kw of keywords) {
+            if (nameLower.includes(kw))
+                score += 10;
+            if (descLower.includes(kw))
+                score += 3;
+        }
+        // Exact name match bonus
+        if (nameLower === queryLower)
+            score += 50;
+        return { tool, score };
+    });
+    const matches = scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+    if (matches.length === 0) {
+        return `No tools matching "${query}". Available tools: ${allTools.map((t) => t.name).join(", ")}`;
+    }
+    return matches.map((m) => formatTool(m.tool)).join("\n\n---\n\n");
+}
+function formatTool(tool) {
+    return (`### ${tool.name}\n` +
+        `Source: ${tool.source}${tool.serverName ? ` (${tool.serverName})` : ""}\n` +
+        `${tool.description}\n` +
+        `Parameters: ${JSON.stringify(tool.inputSchema, null, 2)}`);
+}

package/dist/tool-system/builtin/web-fetch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Built-in WebFetch tool — fetch a URL and extract readable text content.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const webFetchToolDef: ToolDefinition;
+type DnsLookup = (hostname: string) => Promise<string[]>;
+/** Test hook: replace the DNS resolver. Pass `null` to restore default. */
+export declare function __setDnsLookupForTests(impl: DnsLookup | null): void;
+export declare function webFetchTool(args: Record<string, unknown>): Promise<string>;
+export {};

package/dist/tool-system/builtin/web-fetch.js

@@ -0,0 +1,328 @@
+/**
+ * Built-in WebFetch tool — fetch a URL and extract readable text content.
+ */
+import * as dns from "node:dns/promises";
+import * as net from "node:net";
+export const webFetchToolDef = {
+    name: "WebFetch",
+    description: "Fetch a web page and return its text content. Strips HTML tags to return readable text. " +
+        "Use this to read articles, documentation, or any web page.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            url: { type: "string", description: "The URL to fetch" },
+            max_length: {
+                type: "number",
+                description: "Maximum characters to return (default: 50000)",
+            },
+            headers: {
+                type: "object",
+                description: "Optional HTTP headers to send",
+            },
+        },
+        required: ["url"],
+    },
+};
+const MAX_OUTPUT = 100_000;
+const DEFAULT_MAX = 50_000;
+// Header names that must not be overridable via args.headers (SSRF / auth injection)
+const BLOCKED_REQUEST_HEADERS = new Set([
+    "host", "authorization", "cookie", "proxy-authorization",
+    "x-forwarded-for", "x-real-ip", "x-forwarded-host",
+]);
+// Hostname patterns that block SSRF to internal/metadata services
+const BLOCKED_HOST_PATTERNS = [
+    /^localhost$/i,
+    /^127\./,
+    /^0\.0\.0\.0$/,
+    /^10\./,
+    /^169\.254\./, // link-local + AWS/GCP metadata (169.254.169.254)
+    /^192\.168\./,
+    /^172\.(1[6-9]|2[0-9]|3[01])\./, // 172.16.0.0/12
+    /^::1$/,
+    /^fc00:/i, /^fd00:/i, // IPv6 ULA
+    /^fe80:/i, // IPv6 link-local
+];
+function isBlockedHost(hostname) {
+    // `new URL("http://[::1]/").hostname` returns "[::1]" (with brackets);
+    // strip them so IPv6 patterns match.
+    const stripped = hostname.startsWith("[") && hostname.endsWith("]")
+        ? hostname.slice(1, -1)
+        : hostname;
+    return BLOCKED_HOST_PATTERNS.some((re) => re.test(stripped));
+}
+// A3 hardening: per-IP block list. Used after DNS resolution to catch
+// public-looking hostnames that resolve to private/loopback addresses
+// (DNS rebinding, AWS metadata via DNS, etc.). See spec
+// docs/superpowers/specs/2026-05-26-a3-webfetch-ssrf-design.md.
+function isBlockedIp(ip) {
+    // Normalize IPv4-mapped IPv6 (e.g. ::ffff:127.0.0.1) so the IPv4
+    // checks below catch it.
+    const mapped = ip.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mapped)
+        return isBlockedIpv4(mapped[1]);
+    if (net.isIPv4(ip))
+        return isBlockedIpv4(ip);
+    if (net.isIPv6(ip))
+        return isBlockedIpv6(ip);
+    // Unknown format — refuse rather than allow.
+    return true;
+}
+function isBlockedIpv4(ip) {
+    const parts = ip.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)) {
+        return true;
+    }
+    const [a, b] = parts;
+    // 0.0.0.0/8 (current network), 10.0.0.0/8, 127.0.0.0/8
+    if (a === 0 || a === 10 || a === 127)
+        return true;
+    // 100.64.0.0/10 — CGNAT
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    // 169.254.0.0/16 — link-local + cloud metadata
+    if (a === 169 && b === 254)
+        return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    // 224.0.0.0/4 multicast, 240.0.0.0/4 reserved/broadcast
+    if (a >= 224)
+        return true;
+    return false;
+}
+function isBlockedIpv6(ip) {
+    const lower = ip.toLowerCase();
+    // Loopback ::1
+    if (lower === "::1")
+        return true;
+    // Unique-local fc00::/7 (covers fc00: and fd00:)
+    if (/^f[cd][0-9a-f]{2}:/.test(lower))
+        return true;
+    // Link-local fe80::/10
+    if (/^fe[89ab][0-9a-f]:/.test(lower))
+        return true;
+    // Documentation 2001:db8::/32
+    if (/^2001:0?db8:/.test(lower))
+        return true;
+    // Discard prefix 100::/64
+    if (/^100:0{0,4}(:|$)/.test(lower))
+        return true;
+    return false;
+}
+// Hop limit for redirect chains.
+const MAX_REDIRECTS = 5;
+// Headers that must be stripped when a redirect crosses origins.
+// Same policy fetch(... redirect: "follow") applies internally; we
+// re-implement it here because we drive redirects manually.
+const CROSS_ORIGIN_STRIP_HEADERS = new Set([
+    "authorization",
+    "cookie",
+    "proxy-authorization",
+]);
+async function defaultDnsLookup(hostname) {
+    // For literal IPs, lookup returns the IP itself (Node behavior),
+    // which still flows through the block-list check above.
+    const records = await dns.lookup(hostname, { all: true, verbatim: true });
+    return records.map((r) => r.address);
+}
+let dnsLookupImpl = defaultDnsLookup;
+/** Test hook: replace the DNS resolver. Pass `null` to restore default. */
+export function __setDnsLookupForTests(impl) {
+    dnsLookupImpl = impl ?? defaultDnsLookup;
+}
+async function validateHopHost(u) {
+    if (u.protocol !== "http:" && u.protocol !== "https:") {
+        return { ok: false, reason: `protocol "${u.protocol}" is not allowed` };
+    }
+    if (isBlockedHost(u.hostname)) {
+        return { ok: false, reason: `host "${u.hostname}" is on the block list` };
+    }
+    let ips;
+    try {
+        ips = await dnsLookupImpl(u.hostname);
+    }
+    catch (err) {
+        return { ok: false, reason: `DNS lookup failed for "${u.hostname}": ${err.message}` };
+    }
+    if (ips.length === 0) {
+        return { ok: false, reason: `DNS returned no addresses for "${u.hostname}"` };
+    }
+    for (const ip of ips) {
+        if (isBlockedIp(ip)) {
+            return {
+                ok: false,
+                reason: `"${u.hostname}" resolves to blocked IP ${ip}`,
+            };
+        }
+    }
+    return { ok: true, ips };
+}
+function sameOrigin(a, b) {
+    return a.protocol === b.protocol && a.host === b.host;
+}
+export async function webFetchTool(args) {
+    const url = args.url;
+    if (!url)
+        return "Error: url is required";
+    // Validate URL
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return `Error: invalid URL "${url}"`;
+    }
+    const maxLength = Math.min(args.max_length || DEFAULT_MAX, MAX_OUTPUT);
+    const rawHeaders = args.headers ?? {};
+    const baseHeaders = {
+        "User-Agent": "Mozilla/5.0 (compatible; code-shell/0.1; +https://github.com/nicepkg/code-shell)",
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,text/plain;q=0.8,*/*;q=0.7",
+    };
+    // Strip dangerous user-supplied headers up-front.
+    for (const [k, v] of Object.entries(rawHeaders)) {
+        if (!BLOCKED_REQUEST_HEADERS.has(k.toLowerCase())) {
+            baseHeaders[k] = v;
+        }
+    }
+    // A3 hardening: manual redirect loop. Each hop revalidates the URL,
+    // host, and DNS-resolved IPs against the block lists. fetch() runs
+    // with redirect: "manual" so the runtime cannot silently follow a
+    // redirect into private/loopback/metadata space.
+    const timeoutSignal = AbortSignal.timeout(30_000);
+    let currentUrl = parsed;
+    let currentHeaders = { ...baseHeaders };
+    const originalOrigin = parsed;
+    try {
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            const check = await validateHopHost(currentUrl);
+            if (!check.ok) {
+                const verb = hop === 0 ? "fetch" : `follow redirect to`;
+                return `Error: refusing to ${verb} ${currentUrl.href} — ${check.reason}`;
+            }
+            const res = await fetch(currentUrl, {
+                headers: currentHeaders,
+                redirect: "manual",
+                signal: timeoutSignal,
+            });
+            // Not a redirect: return body (or HTTP error).
+            if (res.status < 300 || res.status >= 400 || !res.headers.get("location")) {
+                if (!res.ok) {
+                    return `Error: HTTP ${res.status} ${res.statusText}`;
+                }
+                return await readAndTruncateBody(res, maxLength);
+            }
+            // Redirect: resolve target, drop credentials on cross-origin,
+            // and loop.
+            const location = res.headers.get("location");
+            let nextUrl;
+            try {
+                nextUrl = new URL(location, currentUrl);
+            }
+            catch {
+                return `Error: redirect target "${location}" is not a valid URL`;
+            }
+            if (!sameOrigin(nextUrl, originalOrigin)) {
+                currentHeaders = stripCrossOriginHeaders(currentHeaders);
+            }
+            currentUrl = nextUrl;
+        }
+        return `Error: too many redirects (max ${MAX_REDIRECTS})`;
+    }
+    catch (err) {
+        const msg = err.message;
+        if (msg.includes("abort") || msg.includes("timeout")) {
+            return "Error: request timed out after 30s";
+        }
+        return `Fetch error: ${msg}`;
+    }
+}
+async function readAndTruncateBody(res, maxLength) {
+    const contentType = res.headers.get("content-type") ?? "";
+    const body = await res.text();
+    let text;
+    if (contentType.includes("text/html") || contentType.includes("application/xhtml")) {
+        text = extractTextFromHTML(body);
+    }
+    else {
+        text = body;
+    }
+    if (text.length > maxLength) {
+        text = text.slice(0, maxLength) + `\n\n... content truncated (${text.length} chars total)`;
+    }
+    return text || "(page returned empty content)";
+}
+function stripCrossOriginHeaders(headers) {
+    const stripped = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (!CROSS_ORIGIN_STRIP_HEADERS.has(k.toLowerCase())) {
+            stripped[k] = v;
+        }
+    }
+    return stripped;
+}
+/**
+ * Simple HTML → text extraction.
+ * Strips tags, decodes common entities, collapses whitespace.
+ * Not perfect, but good enough for most web pages.
+ */
+function extractTextFromHTML(html) {
+    let text = html;
+    // Remove script and style blocks
+    text = text.replace(/<script[\s\S]*?<\/script>/gi, "");
+    text = text.replace(/<style[\s\S]*?<\/style>/gi, "");
+    text = text.replace(/<noscript[\s\S]*?<\/noscript>/gi, "");
+    // Extract title
+    const titleMatch = text.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+    const title = titleMatch ? decodeEntities(titleMatch[1].trim()) : "";
+    // Try to extract main content area
+    const mainMatch = text.match(/<main[\s\S]*?<\/main>/i) ??
+        text.match(/<article[\s\S]*?<\/article>/i) ??
+        text.match(/<div[^>]*(?:role="main"|id="content"|class="[^"]*content[^"]*")[^>]*>[\s\S]*?<\/div>/i);
+    if (mainMatch) {
+        text = mainMatch[0];
+    }
+    else {
+        // Fall back to body
+        const bodyMatch = text.match(/<body[\s\S]*?<\/body>/i);
+        if (bodyMatch)
+            text = bodyMatch[0];
+    }
+    // Remove nav, header, footer, aside
+    text = text.replace(/<(nav|header|footer|aside)[\s\S]*?<\/\1>/gi, "");
+    // Convert block elements to newlines
+    text = text.replace(/<(p|div|h[1-6]|li|br|tr|blockquote)[^>]*>/gi, "\n");
+    text = text.replace(/<\/(p|div|h[1-6]|li|tr|blockquote)>/gi, "\n");
+    text = text.replace(/<hr[^>]*>/gi, "\n---\n");
+    // Remove all remaining tags
+    text = text.replace(/<[^>]+>/g, "");
+    // Decode entities
+    text = decodeEntities(text);
+    // Collapse whitespace
+    text = text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0)
+        .join("\n");
+    // Remove excessive blank lines
+    text = text.replace(/\n{3,}/g, "\n\n");
+    if (title) {
+        text = `# ${title}\n\n${text}`;
+    }
+    return text.trim();
+}
+function decodeEntities(text) {
+    return text
+        .replace(/&amp;/g, "&")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&nbsp;/g, " ")
+        .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
+}

package/dist/tool-system/builtin/web-search.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Built-in WebSearch tool — search the web via Serper, Tavily, or SearXNG.
+ *
+ * Provider selection / credentials are read in this precedence:
+ *   1. settings.search.{provider, apiKey, baseUrl} from ~/.code-shell/settings.json
+ *      (set via the desktop "连接" UI or hand-edited)
+ *   2. env vars SERPER_API_KEY / TAVILY_API_KEY / SEARXNG_URL (legacy / CI override)
+ * Settings take precedence so the desktop UI's "保存连接" + "测试连接" is the
+ * single source of truth for end users.
+ */
+import type { ToolDefinition } from "../../types.js";
+export type SearchProvider = "serper" | "tavily" | "searxng";
+export interface ResolvedSearchConfig {
+    provider: SearchProvider;
+    apiKey?: string;
+    baseUrl?: string;
+    source: "settings" | "env" | "none";
+}
+/**
+ * Resolve the active search config. Returns `source` so callers can show
+ * the user where the value came from when debugging.
+ */
+export declare function resolveSearchConfig(cwd?: string): ResolvedSearchConfig;
+export declare const webSearchToolDef: ToolDefinition;
+export declare function webSearchTool(args: Record<string, unknown>): Promise<string>;