@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/tools/server.js

@@ -0,0 +1,249 @@
+/**
+ * Managed development server tools.
+ */
+import { gateToolAction } from "../approval/tool-helper.js";
+import { getManagedServer, getManagedServerLogs, listManagedServers, startManagedServer, stopManagedServer, } from "./server-manager.js";
+export function createManagedServerTools(cwd, approval) {
+    return [
+        {
+            name: "start_server",
+            deferred: true,
+            effect: "unknown",
+            requiresApproval: true,
+            description: "Start a long-running development server as a managed service. Use this instead of bash for npm run dev, next dev, vite, webpack --watch, or similar commands. Pass a foreground server command without a trailing '&'. The tool waits for readiness and then returns a server_id; use server_status, server_logs, and stop_server to manage it.",
+            parameters: {
+                type: "object",
+                properties: {
+                    command: { type: "string", description: "Foreground server command to run, for example npm run dev" },
+                    port: { type: "number", description: "Expected localhost port, used for readiness checks and conflict detection" },
+                    readinessUrl: { type: "string", description: "URL to poll until the server is ready. Defaults to http://localhost:<port> when port is provided." },
+                    timeout: { type: "number", description: "Seconds to wait for readiness. Defaults to 30." },
+                    purpose: { type: "string", enum: ["preview", "verification"], description: "Why the server is being started." },
+                    lifecycle: { type: "string", enum: ["auto", "keep_alive"], description: "auto stops at the end of the agent run; keep_alive remains available until stop_server or process exit." },
+                },
+                required: ["command"],
+                additionalProperties: false,
+            },
+            async execute(args, ctx) {
+                const command = String(args.command ?? "").trim();
+                if (!command) {
+                    return {
+                        content: "Error: command is required",
+                        isError: true,
+                        status: "blocked",
+                        metadata: { kind: "server", reason: "missing_command" },
+                    };
+                }
+                if (command.endsWith("&")) {
+                    return {
+                        content: "Error: start_server expects a foreground command. Remove the trailing '&' so Bubble can own the server lifecycle.",
+                        isError: true,
+                        status: "blocked",
+                        metadata: { kind: "server", reason: "background_command" },
+                    };
+                }
+                const gate = await gateToolAction(approval, { type: "bash", command, cwd });
+                if (!gate.approved)
+                    return gate.result;
+                const purpose = parsePurpose(args.purpose);
+                const lifecycle = parseLifecycle(args.lifecycle, purpose);
+                const timeoutSec = typeof args.timeout === "number" && args.timeout > 0 ? args.timeout : 30;
+                try {
+                    const server = await startManagedServer({
+                        command,
+                        cwd: ctx.cwd || cwd,
+                        port: parsePort(args.port),
+                        readinessUrl: typeof args.readinessUrl === "string" && args.readinessUrl.trim()
+                            ? args.readinessUrl.trim()
+                            : undefined,
+                        timeoutSec,
+                        ownerSessionId: ctx.sessionID,
+                        ownerRunId: ctx.toolCall?.id,
+                        purpose,
+                        lifecycle,
+                    });
+                    return {
+                        content: formatServerStarted(server),
+                        status: "success",
+                        metadata: serverMetadata(server),
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: `Error: ${error.message ?? String(error)}`,
+                        isError: true,
+                        status: "command_error",
+                        metadata: {
+                            kind: "server",
+                            reason: "start_failed",
+                            command,
+                            port: parsePort(args.port),
+                        },
+                    };
+                }
+            },
+        },
+        {
+            name: "server_status",
+            deferred: true,
+            readOnly: true,
+            effect: "read",
+            description: "Show managed development server status. Pass serverId for one server, or omit it to list all managed servers.",
+            parameters: {
+                type: "object",
+                properties: {
+                    serverId: { type: "string", description: "Managed server id returned by start_server" },
+                },
+                additionalProperties: false,
+            },
+            async execute(args) {
+                const serverId = typeof args.serverId === "string" ? args.serverId.trim() : "";
+                if (serverId) {
+                    const server = getManagedServer(serverId);
+                    if (!server)
+                        return missingServer(serverId);
+                    return {
+                        content: formatServer(server),
+                        status: "success",
+                        metadata: serverMetadata(server),
+                    };
+                }
+                const servers = listManagedServers();
+                if (servers.length === 0) {
+                    return {
+                        content: "No managed servers.",
+                        status: "no_match",
+                        metadata: { kind: "server", count: 0 },
+                    };
+                }
+                return {
+                    content: servers.map(formatServer).join("\n\n"),
+                    status: "success",
+                    metadata: { kind: "server", count: servers.length },
+                };
+            },
+        },
+        {
+            name: "server_logs",
+            deferred: true,
+            readOnly: true,
+            effect: "read",
+            description: "Return recent logs for a managed development server.",
+            parameters: {
+                type: "object",
+                properties: {
+                    serverId: { type: "string", description: "Managed server id returned by start_server" },
+                    maxCharacters: { type: "number", description: "Maximum log characters to return. Defaults to 12000." },
+                },
+                required: ["serverId"],
+                additionalProperties: false,
+            },
+            async execute(args) {
+                const serverId = String(args.serverId ?? "").trim();
+                if (!serverId)
+                    return missingServer(serverId);
+                const maxChars = typeof args.maxCharacters === "number" && args.maxCharacters > 0
+                    ? Math.min(args.maxCharacters, 50000)
+                    : 12000;
+                const logs = getManagedServerLogs(serverId, maxChars);
+                if (logs === undefined)
+                    return missingServer(serverId);
+                return {
+                    content: logs.trim() || "(no logs captured)",
+                    status: "success",
+                    metadata: { kind: "server", serverId, maxCharacters: maxChars },
+                };
+            },
+        },
+        {
+            name: "stop_server",
+            deferred: true,
+            effect: "unknown",
+            description: "Stop a managed development server by serverId.",
+            parameters: {
+                type: "object",
+                properties: {
+                    serverId: { type: "string", description: "Managed server id returned by start_server" },
+                },
+                required: ["serverId"],
+                additionalProperties: false,
+            },
+            async execute(args) {
+                const serverId = String(args.serverId ?? "").trim();
+                if (!serverId)
+                    return missingServer(serverId);
+                const server = await stopManagedServer(serverId);
+                if (!server)
+                    return missingServer(serverId);
+                return {
+                    content: `Stopped ${server.id}.`,
+                    status: "success",
+                    metadata: serverMetadata(server),
+                };
+            },
+        },
+    ];
+}
+function parsePurpose(value) {
+    return value === "verification" ? "verification" : "preview";
+}
+function parseLifecycle(value, purpose) {
+    if (value === "auto" || value === "keep_alive")
+        return value;
+    return purpose === "verification" ? "auto" : "keep_alive";
+}
+function parsePort(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= 0 || value > 65535) {
+        return undefined;
+    }
+    return value;
+}
+function formatServerStarted(server) {
+    const lines = [`Started ${server.id}.`];
+    if (server.url)
+        lines.push(`URL: ${server.url}`);
+    if (server.port)
+        lines.push(`Port: ${server.port}`);
+    lines.push(`Status: ${server.status}`);
+    lines.push(`Lifecycle: ${server.lifecycle}`);
+    return lines.join("\n");
+}
+function formatServer(server) {
+    return [
+        `${server.id}: ${server.status}`,
+        `Command: ${server.command}`,
+        `CWD: ${server.cwd}`,
+        server.url ? `URL: ${server.url}` : undefined,
+        server.port ? `Port: ${server.port}` : undefined,
+        `Purpose: ${server.purpose}`,
+        `Lifecycle: ${server.lifecycle}`,
+        server.pid ? `PID: ${server.pid}` : undefined,
+        server.exitCode !== undefined ? `Exit code: ${server.exitCode}` : undefined,
+    ].filter(Boolean).join("\n");
+}
+function serverMetadata(server) {
+    return {
+        kind: "server",
+        serverId: server.id,
+        status: server.status,
+        command: server.command,
+        cwd: server.cwd,
+        port: server.port,
+        url: server.url,
+        purpose: server.purpose,
+        lifecycle: server.lifecycle,
+        pid: server.pid,
+    };
+}
+function missingServer(serverId) {
+    return {
+        content: serverId ? `Error: Managed server not found: ${serverId}` : "Error: serverId is required",
+        isError: true,
+        status: "no_match",
+        metadata: {
+            kind: "server",
+            serverId,
+            reason: "server_not_found",
+        },
+    };
+}

package/dist/tools/skill-search.d.ts

@@ -0,0 +1,10 @@
+import type { SkillRegistry } from "../skills/registry.js";
+import type { SkillSummary } from "../skills/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+interface SkillSearchMatch {
+    skill: SkillSummary;
+    score: number;
+}
+export declare function createSkillSearchTool(registry: SkillRegistry): ToolRegistryEntry;
+export declare function searchSkillSummaries(skills: SkillSummary[], query: string): SkillSearchMatch[];
+export {};

package/dist/tools/skill-search.js

@@ -0,0 +1,134 @@
+const DEFAULT_MAX_RESULTS = 8;
+const MAX_RESULTS = 25;
+const SOURCE_PRIORITY = {
+    project: 0,
+    configured: 1,
+    user: 2,
+};
+export function createSkillSearchTool(registry) {
+    return {
+        name: "skill_search",
+        readOnly: true,
+        effect: "read",
+        description: "Search available skills by name, description, tags, and source. Use this before loading a skill when a task may match a specialized workflow.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search terms describing the desired skill or workflow.",
+                },
+                max_results: {
+                    type: "number",
+                    description: `Maximum number of matches to return (default ${DEFAULT_MAX_RESULTS}, max ${MAX_RESULTS}).`,
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        async execute(args) {
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            const maxResults = typeof args.max_results === "number" && args.max_results > 0
+                ? Math.min(Math.floor(args.max_results), MAX_RESULTS)
+                : DEFAULT_MAX_RESULTS;
+            const skills = registry.summaries();
+            if (skills.length === 0) {
+                return { content: "No skills are currently available." };
+            }
+            const matches = searchSkillSummaries(skills, query).slice(0, maxResults);
+            if (matches.length === 0) {
+                return {
+                    content: `No skills matched "${query}". Try broader terms or use /skills to browse all skills manually.`,
+                };
+            }
+            return {
+                content: formatSkillSearchResults(matches, skills.length, query),
+            };
+        },
+    };
+}
+export function searchSkillSummaries(skills, query) {
+    const terms = normalizeTerms(query);
+    const scored = [];
+    for (const skill of skills) {
+        const score = scoreSkill(skill, terms, query);
+        if (score > 0 || terms.length === 0) {
+            scored.push({ skill, score });
+        }
+    }
+    scored.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        const ap = SOURCE_PRIORITY[a.skill.source ?? "user"] ?? 3;
+        const bp = SOURCE_PRIORITY[b.skill.source ?? "user"] ?? 3;
+        if (ap !== bp)
+            return ap - bp;
+        return a.skill.name.localeCompare(b.skill.name);
+    });
+    return scored;
+}
+function scoreSkill(skill, terms, rawQuery) {
+    const name = skill.name.toLowerCase();
+    const desc = (skill.description ?? "").toLowerCase();
+    const tags = (skill.tags ?? []).map((tag) => tag.toLowerCase());
+    const source = skill.source ?? "user";
+    const sourceBonus = source === "project" ? 4 : source === "configured" ? 2 : 0;
+    const query = rawQuery.trim().toLowerCase();
+    if (terms.length === 0)
+        return 1 + sourceBonus;
+    let score = 0;
+    if (name === query)
+        score += 80;
+    if (name.includes(query) && query.length > 0)
+        score += 30;
+    for (const term of terms) {
+        if (name === term)
+            score += 30;
+        else if (name.includes(term))
+            score += 12;
+        if (tags.some((tag) => tag === term))
+            score += 10;
+        else if (tags.some((tag) => tag.includes(term)))
+            score += 6;
+        if (desc.includes(term))
+            score += 3;
+        if (source.includes(term))
+            score += 2;
+    }
+    return score > 0 ? score + sourceBonus : 0;
+}
+function normalizeTerms(query) {
+    const rawTerms = query
+        .toLowerCase()
+        .split(/[^a-z0-9_\-\u3000-\u9fff]+/i)
+        .map((term) => term.trim())
+        .filter(Boolean);
+    const terms = new Set();
+    for (const term of rawTerms) {
+        terms.add(term);
+        const chars = Array.from(term);
+        if (chars.some(isCjkChar) && chars.length > 2) {
+            for (let i = 0; i < chars.length - 1; i++) {
+                terms.add(`${chars[i]}${chars[i + 1]}`);
+            }
+        }
+    }
+    return [...terms];
+}
+function isCjkChar(ch) {
+    const code = ch.codePointAt(0) ?? 0;
+    return code >= 0x3000 && code <= 0x9fff;
+}
+function formatSkillSearchResults(matches, total, query) {
+    const lines = [
+        query ? `Skill search results for "${query}" (${matches.length} of ${total}):` : `Available skills (${matches.length} of ${total}):`,
+    ];
+    for (const { skill } of matches) {
+        const tags = skill.tags && skill.tags.length > 0 ? ` [tags: ${skill.tags.join(", ")}]` : "";
+        const source = skill.source ? ` (${skill.source})` : "";
+        lines.push(`- ${skill.name}${source}: ${skill.description}${tags}`);
+    }
+    lines.push("");
+    lines.push("Call skill with the exact name to load a selected skill.");
+    return lines.join("\n");
+}

package/dist/tools/skill.d.ts

@@ -0,0 +1,7 @@
+import type { SkillRecord } from "../skills/types.js";
+import type { SkillRegistry } from "../skills/registry.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function formatLoadedSkill(skill: SkillRecord): string;
+export declare function createSkillTool(registry: SkillRegistry): ToolRegistryEntry;
+/** Up to three known names closest to a mistyped one (substring first, then edit distance). */
+export declare function closestSkillNames(name: string, names: string[]): string[];

package/dist/tools/skill.js

@@ -0,0 +1,81 @@
+export function formatLoadedSkill(skill) {
+    const resources = [
+        ...skill.resources.references,
+        ...skill.resources.scripts,
+        ...skill.resources.assets,
+    ];
+    const sections = [
+        `Skill: ${skill.meta.name}`,
+        `Description: ${skill.meta.description}`,
+        `Base directory: ${skill.rootDir}`,
+        "",
+        skill.content,
+    ];
+    if (resources.length > 0) {
+        sections.push("", "Resources:", ...resources.map((resource) => `- ${resource}`));
+    }
+    sections.push("", "Relative paths mentioned in this skill are resolved from the base directory above.");
+    return sections.join("\n");
+}
+export function createSkillTool(registry) {
+    return {
+        name: "skill",
+        readOnly: true,
+        effect: "read",
+        description: "Load a skill by its exact name, as listed in the Skills section of the system prompt. Returns the skill's instructions; follow them for the task.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The exact skill name to load" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        async execute(args) {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name) {
+                return { content: "Error: skill name is required", isError: true };
+            }
+            const skill = registry.get(name);
+            if (!skill) {
+                const close = closestSkillNames(name, registry.summaries().map((s) => s.name));
+                return {
+                    content: `Error: Unknown skill "${name}".` +
+                        (close.length ? ` Did you mean: ${close.join(", ")}?` : "") +
+                        " Use the exact name from the Skills section.",
+                    isError: true,
+                };
+            }
+            return { content: formatLoadedSkill(skill) };
+        },
+    };
+}
+/** Up to three known names closest to a mistyped one (substring first, then edit distance). */
+export function closestSkillNames(name, names) {
+    const target = name.toLowerCase();
+    const scored = names.map((candidate) => {
+        const lower = candidate.toLowerCase();
+        // Substring matches only for real fragments; a 1–2 letter typo would match everything.
+        const contains = target.length >= 3 && (lower.includes(target) || target.includes(lower));
+        return { candidate, score: contains ? 0 : editDistance(target, lower) };
+    });
+    const limit = Math.max(2, Math.floor(target.length / 3));
+    return scored
+        .filter((s) => s.score <= limit)
+        .sort((a, b) => a.score - b.score || a.candidate.localeCompare(b.candidate))
+        .slice(0, 3)
+        .map((s) => s.candidate);
+}
+function editDistance(a, b) {
+    const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        let prev = row[0];
+        row[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cur = row[j];
+            row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = cur;
+        }
+    }
+    return row[b.length];
+}

package/dist/tools/task-tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Deferred background-task tools (background-tasks design §2.1).
+ *
+ * Both are deferred: sessions that never background anything pay zero schema
+ * cost. The bash spawn path unlocks them programmatically the moment the
+ * first task exists, so there is no tool_search hop in practice.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+import type { ProcessManager } from "../tasks/manager.js";
+export declare function createBackgroundTaskTools(manager: ProcessManager): ToolRegistryEntry[];

package/dist/tools/task-tools.js

@@ -0,0 +1,133 @@
+/**
+ * Deferred background-task tools (background-tasks design §2.1).
+ *
+ * Both are deferred: sessions that never background anything pay zero schema
+ * cost. The bash spawn path unlocks them programmatically the moment the
+ * first task exists, so there is no tool_search hop in practice.
+ */
+const MAX_IDS_PER_CALL = 20;
+const OUTPUT_TAIL_CHARS = 12000;
+export function createBackgroundTaskTools(manager) {
+    return [
+        {
+            name: "task_output",
+            deferred: true,
+            readOnly: true,
+            effect: "read",
+            description: "Check background tasks started with bash run_in_background. Without wait_ms returns an immediate snapshot (status, elapsed, exit code, output tail). With wait_ms, blocks until the wait mode is satisfied or the deadline passes — a timeout is not an error; call again with a longer wait_ms. Never poll with foreground sleep; use wait_ms instead.",
+            parameters: {
+                type: "object",
+                properties: {
+                    task_ids: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Background task ids (task_XXXX). Max 20. Subagents use wait_agent; workflows use wait_workflow; servers use server_status.",
+                    },
+                    wait_ms: { type: "number", description: "Block up to this many milliseconds for completion. Omit for an immediate snapshot." },
+                    mode: { type: "string", enum: ["any", "all"], description: "With wait_ms: resolve when any (default) or all listed tasks finish." },
+                },
+                required: ["task_ids"],
+                additionalProperties: false,
+            },
+            async execute(args) {
+                const ids = normalizeIds(args.task_ids);
+                if (!ids.length) {
+                    return { content: "Error: task_output requires at least one task id.", isError: true };
+                }
+                if (ids.length > MAX_IDS_PER_CALL) {
+                    return { content: `Error: task_output accepts at most ${MAX_IDS_PER_CALL} task ids per call.`, isError: true };
+                }
+                const unknown = ids.filter((id) => !manager.getTask(id));
+                if (unknown.length) {
+                    return {
+                        content: `Error: unknown task id${unknown.length > 1 ? "s" : ""}: ${unknown.join(", ")}. Use ids returned by bash run_in_background.`,
+                        isError: true,
+                    };
+                }
+                const waitMs = typeof args.wait_ms === "number" && args.wait_ms > 0 ? args.wait_ms : undefined;
+                const mode = args.mode === "all" ? "all" : "any";
+                const tasks = waitMs !== undefined
+                    ? await manager.waitTasks(ids, { timeoutMs: waitMs, mode })
+                    : ids.map((id) => manager.getTask(id)).filter(Boolean);
+                const stillRunning = tasks.filter((task) => task.status === "running");
+                const lines = [];
+                if (waitMs !== undefined && stillRunning.length > 0) {
+                    lines.push(`task_output timed out after ${waitMs}ms with ${stillRunning.length} task(s) still running.`, "This is not a failure — call task_output again with a longer wait_ms instead of re-running the work.", "");
+                }
+                for (const task of tasks) {
+                    lines.push(...formatTask(task, manager));
+                    lines.push("");
+                    // Reading a finished task counts as delivery (design §2.3a).
+                    if (task.status !== "running")
+                        manager.markTaskDelivered(task.id);
+                }
+                return {
+                    content: lines.join("\n").trim(),
+                    status: waitMs !== undefined && stillRunning.length > 0 ? "timeout" : "success",
+                    metadata: { kind: "shell", background: true },
+                };
+            },
+        },
+        {
+            name: "kill_task",
+            deferred: true,
+            effect: "unknown",
+            description: "Terminate a background task started with bash run_in_background (SIGTERM, then SIGKILL). Use only when the task is no longer needed or is misbehaving.",
+            parameters: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "Background task id (task_XXXX)." },
+                },
+                required: ["task_id"],
+                additionalProperties: false,
+            },
+            async execute(args) {
+                const id = String(args.task_id ?? "").trim();
+                const existing = manager.getTask(id);
+                if (!existing) {
+                    return { content: `Error: unknown task id: ${id || "(empty)"}.`, isError: true };
+                }
+                const alreadyFinished = (task) => ({
+                    content: `Task ${id} already finished (${task.status}${task.exitCode != null ? `, exit ${task.exitCode}` : ""}). Nothing to kill.`,
+                    status: "success",
+                    metadata: { kind: "shell", background: true },
+                });
+                if (existing.status !== "running")
+                    return alreadyFinished(existing);
+                const killed = await manager.killTask(id);
+                // The task can exit on its own just before the kill lands; the manager
+                // then keeps its real outcome, so do not claim we killed it.
+                if (killed && killed.status !== "killed")
+                    return alreadyFinished(killed);
+                return {
+                    content: `Killed background task ${id}${killed?.description ? ` (${killed.description})` : ""}.`,
+                    status: "success",
+                    metadata: { kind: "shell", background: true },
+                };
+            },
+        },
+    ];
+}
+function normalizeIds(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const ids = raw.map((value) => String(value).trim()).filter(Boolean);
+    return [...new Set(ids)];
+}
+function formatTask(task, manager) {
+    const elapsedMs = (task.endedAt ?? Date.now()) - task.startedAt;
+    const elapsed = `${Math.round(elapsedMs / 1000)}s`;
+    const header = task.status === "running"
+        ? `${task.id}: running for ${elapsed}${task.description ? ` — ${task.description}` : ""}`
+        : `${task.id}: ${task.status}${task.exitCode != null ? ` (exit ${task.exitCode})` : ""} in ${elapsed}${task.description ? ` — ${task.description}` : ""}`;
+    const lines = [header, `  command: ${task.command}`];
+    const output = manager.taskOutputTail(task.id, OUTPUT_TAIL_CHARS);
+    if (output && output.trim()) {
+        lines.push(`  output${task.outputTruncated ? " (tail, truncated)" : ""}:`);
+        lines.push(...output.trimEnd().split("\n").map((line) => `    ${line}`));
+    }
+    else {
+        lines.push("  output: (none captured)");
+    }
+    return lines;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * tool_search — meta-tool that loads schemas for deferred tools on demand.
+ *
+ * Mirrors Claude Code's ToolSearch. Two query modes:
+ *
+ *   - "select:a,b,c"  → fetch these exact tools by name (ignores ranking)
+ *   - free text       → rank deferred tools by substring match against name
+ *                       and description, return the top N
+ *
+ * Output is a <functions>…</functions> block containing one
+ * `<function>{schema JSON}</function>` per match — the same encoding the
+ * provider uses for the tool list at the top of the prompt. The matched
+ * tools are also unlocked on the agent so subsequent turns include them in
+ * the real tool list.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+export interface ToolSearchController {
+    /** All deferred tools in the current session, whether unlocked or not. */
+    listDeferred: () => ToolRegistryEntry[];
+    /** Mark a set of deferred tool names as unlocked. */
+    unlock: (names: string[]) => void;
+}
+export declare function createToolSearchTool(controller?: ToolSearchController): ToolRegistryEntry;