@alisio/core 0.1.0-alpha.3

package/dist/startup/index.js

@@ -0,0 +1,105 @@
+import { DefaultAlisioMascot } from "./mascot.js";
+import { DefaultStartupScreen, shortenPath, startupTips } from "./screen.js";
+import { sanitizeLine, truncate } from "./text.js";
+export { DefaultAlisioMascot } from "./mascot.js";
+export { composeSideBySide, DefaultStartupScreen, infoSection, mascotSection, pluginsSection, shortenPath, startupTips, tipsSection, titleSection, welcomeSection, } from "./screen.js";
+export { padEnd, sanitizeLine, stripAnsi, truncate, visibleWidth } from "./text.js";
+const MAX_LINES = 60;
+/** Synchronous providers cannot be preempted; output slower than this is discarded. */
+const SLOW_MS = 250;
+const DEFAULT_TERMINAL = {
+    color: false,
+    unicode: true,
+    columns: 80,
+    interactive: false,
+};
+function validate(output, terminal, maxLines) {
+    const lines = typeof output === "string" ? output.split("\n") : output;
+    if (!Array.isArray(lines) || !lines.every((l) => typeof l === "string"))
+        throw new Error("render must return a string or an array of strings");
+    if (lines.length > maxLines)
+        throw new Error(`render returned more than ${maxLines} lines`);
+    return lines
+        .flatMap((l) => l.split("\n"))
+        .map((l) => truncate(sanitizeLine(l, terminal), terminal.columns));
+}
+function timed(fn) {
+    const started = Date.now();
+    const value = fn();
+    if (Date.now() - started > SLOW_MS)
+        throw new Error(`render took longer than ${SLOW_MS}ms`);
+    return value;
+}
+export function renderStartup(source, input) {
+    const terminal = input.terminal ?? DEFAULT_TERMINAL;
+    const diagnostics = [];
+    for (const conflict of [
+        ...source.extensions.conflicts("mascot"),
+        ...source.extensions.conflicts("startup-screen"),
+    ])
+        diagnostics.push({ type: "extension_conflict", ...conflict });
+    const fail = (plugin, hook, error) => diagnostics.push({
+        type: "plugin_hook_failed",
+        source: plugin,
+        hook,
+        error: error instanceof Error ? error.message : String(error),
+    });
+    // Mascot: validate once at the requested terminal; a failing provider is replaced.
+    let mascotId = DefaultAlisioMascot.id;
+    let mascotProvider = DefaultAlisioMascot;
+    const chosenMascot = source.extensions.resolve("mascot");
+    if (chosenMascot) {
+        try {
+            timed(() => validate(chosenMascot.provider.render({ terminal, version: input.version }), terminal, 12));
+            mascotProvider = chosenMascot.provider;
+            mascotId = chosenMascot.provider.id;
+        }
+        catch (error) {
+            fail(chosenMascot.plugin, "mascot.render", error);
+        }
+    }
+    // The mascot handed to screens is always safe to call.
+    const safeMascot = {
+        id: mascotId,
+        render(ctx) {
+            try {
+                return validate(mascotProvider.render(ctx), ctx.terminal, 12);
+            }
+            catch {
+                return validate(DefaultAlisioMascot.render(ctx), ctx.terminal, 12);
+            }
+        },
+    };
+    const context = {
+        version: input.version,
+        cwd: shortenPath(input.cwd, Math.max(10, terminal.columns - 14), input.home),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.provider ? { provider: input.provider } : {}),
+        ...(input.userName ? { userName: input.userName } : {}),
+        terminal,
+        plugins: source.metadata(),
+        mascot: safeMascot,
+        tips: startupTips(input.tipSeed ?? Math.floor(Date.now() / 86_400_000)),
+        ...(input.facts ? { facts: input.facts } : {}),
+    };
+    const render = (screen) => timed(() => validate(screen.render(context), terminal, MAX_LINES));
+    const chosenScreen = source.extensions.resolve("startup-screen");
+    if (chosenScreen)
+        try {
+            return {
+                lines: render(chosenScreen.provider),
+                screen: chosenScreen.provider.id,
+                mascot: mascotId,
+                diagnostics,
+            };
+        }
+        catch (error) {
+            fail(chosenScreen.plugin, "startup-screen.render", error);
+        }
+    return {
+        lines: render(DefaultStartupScreen),
+        screen: DefaultStartupScreen.id,
+        mascot: mascotId,
+        diagnostics,
+    };
+}

package/dist/startup/mascot.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Default mascot: "Ali", a small trade-wind cloud spirit (alisio = trade wind) blowing a
+ * gust to the right. Original art; Unicode, ASCII and one-line compact variants.
+ */
+import type { MascotProvider } from "@alisio/sdk";
+export declare const DefaultAlisioMascot: MascotProvider;

package/dist/startup/mascot.js

@@ -0,0 +1,30 @@
+import { sgr } from "./text.js";
+const UNICODE = [
+    "    .-~~~-.     ",
+    "  .(  ◕ ◡ ◕ ).  ≋≋",
+    " (___________)≋≋≋",
+    "    ╰≈≈≈≈≈╯  ≋≋",
+    "     ˙ ˙ ˙",
+];
+const ASCII = [
+    "    .-~~~-.     ",
+    "  .(  o u o ).  ~~",
+    " (___________)~~~",
+    "    `~~~~~'  ~~",
+    "     . . .",
+];
+export const DefaultAlisioMascot = {
+    id: "alisio.default",
+    render(ctx) {
+        const { unicode, color, columns } = ctx.terminal;
+        if (columns < 40) {
+            const line = unicode ? "≋(◕◡◕)≋" : "~(o.o)~";
+            return [sgr(color, "36")(line)];
+        }
+        const cloud = sgr(color, "96"), wind = sgr(color, "34");
+        return (unicode ? UNICODE : ASCII).map((raw) => {
+            const [, body = "", gust = ""] = /^(.*?)([≋~]{2,})?$/u.exec(raw.trimEnd()) ?? [];
+            return `${body ? cloud(body) : ""}${gust ? wind(gust) : ""}`;
+        });
+    },
+};

package/dist/startup/screen.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Default startup screen built from small, reusable section functions. Every section returns
+ * plain lines (SGR only when color is allowed); layout never exceeds `terminal.columns`.
+ */
+import type { StartupContext, StartupScreenProvider } from "@alisio/sdk";
+/** Deterministic tip rotation: the same seed always yields the same tips. */
+export declare function startupTips(seed: number, count?: number): string[];
+export declare function shortenPath(path: string, max: number, home?: string): string;
+export declare function titleSection(ctx: StartupContext): string[];
+export declare function welcomeSection(ctx: StartupContext): string[];
+/** Label/value rows: model, provider host (never keys), working directory, host facts. */
+export declare function infoSection(ctx: StartupContext, width: number): string[];
+export declare function pluginsSection(ctx: StartupContext): string[];
+export declare function tipsSection(ctx: StartupContext): string[];
+export declare function mascotSection(ctx: StartupContext): string[];
+/** Mascot on the left and info on the right, or stacked when there is no room. */
+export declare function composeSideBySide(left: string[], right: string[], columns: number, gap?: number): string[];
+export declare const DefaultStartupScreen: StartupScreenProvider;

package/dist/startup/screen.js

@@ -0,0 +1,116 @@
+import { padEnd, sgr, truncate, visibleWidth } from "./text.js";
+const TIPS = [
+    "Type /help to see every command and key.",
+    "Switch models for the next turn with /model.",
+    "Running out of context? /compact [focus] summarizes older turns.",
+    "Hold Shift while dragging to use your terminal's native selection.",
+    "/stats shows tokens, tools, plugins and context usage.",
+    "Press Esc to interrupt a running turn.",
+    "/memory searches what Alisio remembers about this project.",
+];
+/** Deterministic tip rotation: the same seed always yields the same tips. */
+export function startupTips(seed, count = 2) {
+    const start = Math.abs(Math.trunc(seed)) % TIPS.length;
+    return Array.from({ length: Math.min(count, TIPS.length) }, (_, i) => TIPS[(start + i) % TIPS.length]);
+}
+const glyph = (t, unicode, ascii) => t.unicode ? unicode : ascii;
+export function shortenPath(path, max, home) {
+    let display = home && (path === home || path.startsWith(`${home}/`)) ? `~${path.slice(home.length)}` : path;
+    if (visibleWidth(display) <= max)
+        return display;
+    const parts = display.split("/").filter(Boolean);
+    display = parts.at(-1) ?? display;
+    for (let i = parts.length - 2; i >= 0; i--) {
+        const next = `${parts[i]}/${display}`;
+        if (visibleWidth(`.../${next}`) > max)
+            break;
+        display = next;
+    }
+    return truncate(`.../${display}`, max, "");
+}
+export function titleSection(ctx) {
+    const t = ctx.terminal;
+    const bold = sgr(t.color, "1;96");
+    const dim = sgr(t.color, "2");
+    return [`${bold("Alisio")} ${dim(`v${ctx.version}`)}`];
+}
+export function welcomeSection(ctx) {
+    const name = ctx.userName ? `, ${ctx.userName}` : "";
+    return [`Welcome${name}! Trade winds for your code.`];
+}
+/** Label/value rows: model, provider host (never keys), working directory, host facts. */
+export function infoSection(ctx, width) {
+    const t = ctx.terminal;
+    const label = sgr(t.color, "2");
+    const rows = [];
+    if (ctx.model)
+        rows.push(["model", ctx.model]);
+    if (ctx.provider)
+        rows.push(["provider", ctx.provider]);
+    rows.push(["cwd", ctx.cwd]);
+    for (const f of ctx.facts ?? [])
+        rows.push([f.label, f.value]);
+    const plugins = ctx.plugins.length;
+    rows.push(["plugins", plugins ? `${plugins} loaded` : "none"]);
+    const labelWidth = Math.min(12, Math.max(...rows.map(([l]) => l.length)) + 1);
+    return rows.map(([l, v]) => {
+        const room = Math.max(1, width - labelWidth - 1);
+        const value = l === "cwd" ? shortenPath(v, room) : truncate(v, room);
+        return `${label(padEnd(l, labelWidth))} ${value}`;
+    });
+}
+export function pluginsSection(ctx) {
+    if (!ctx.plugins.length)
+        return [];
+    const t = ctx.terminal;
+    const modelProviders = ctx.plugins.filter((p) => p.categories?.includes("model-provider"));
+    const names = [
+        ...(modelProviders.length
+            ? [`${modelProviders.length} model provider${modelProviders.length === 1 ? "" : "s"}`]
+            : []),
+        ...ctx.plugins
+            .filter((p) => !p.categories?.includes("model-provider"))
+            .map((p) => `${p.id}${p.builtin ? " (builtin)" : ""}`),
+    ];
+    return [`${sgr(t.color, "2")("with")} ${names.join(", ")}`];
+}
+export function tipsSection(ctx) {
+    const t = ctx.terminal;
+    const bullet = sgr(t.color, "33")(glyph(t, "›", ">"));
+    return ctx.tips.map((tip) => `${bullet} Tip: ${tip}`);
+}
+export function mascotSection(ctx) {
+    return [ctx.mascot.render({ terminal: ctx.terminal, version: ctx.version })].flat();
+}
+/** Mascot on the left and info on the right, or stacked when there is no room. */
+export function composeSideBySide(left, right, columns, gap = 3) {
+    const leftWidth = Math.max(0, ...left.map(visibleWidth));
+    const rows = Math.max(left.length, right.length);
+    const out = [];
+    for (let i = 0; i < rows; i++) {
+        const l = padEnd(left[i] ?? "", leftWidth);
+        const r = truncate(right[i] ?? "", Math.max(0, columns - leftWidth - gap));
+        out.push(`${l}${" ".repeat(gap)}${r}`.trimEnd());
+    }
+    return out;
+}
+const SIDE_BY_SIDE_MIN_INFO = 34;
+export const DefaultStartupScreen = {
+    id: "alisio.default",
+    render(ctx) {
+        const columns = Math.max(1, ctx.terminal.columns);
+        const mascot = mascotSection(ctx);
+        const mascotWidth = Math.max(0, ...mascot.map(visibleWidth));
+        const side = mascot.length > 1 && columns - mascotWidth - 3 >= SIDE_BY_SIDE_MIN_INFO;
+        const infoWidth = side ? columns - mascotWidth - 3 : columns;
+        const info = [
+            ...titleSection(ctx),
+            ...welcomeSection(ctx),
+            ...infoSection(ctx, infoWidth),
+            ...pluginsSection(ctx),
+        ];
+        const body = side ? composeSideBySide(mascot, info, columns) : [...mascot, ...info];
+        const rule = sgr(ctx.terminal.color, "2")(glyph(ctx.terminal, "─", "-").repeat(Math.min(columns, 60)));
+        return [...body, "", ...tipsSection(ctx), rule].map((line) => truncate(line, columns));
+    },
+};

package/dist/startup/text.d.ts

@@ -0,0 +1,19 @@
+/** Terminal text helpers for startup rendering (no pi-tui dependency). */
+declare const SGR: RegExp;
+export declare const stripAnsi: (text: string) => string;
+/** Printable width in columns (code points; wide East Asian glyphs count as one). */
+export declare const visibleWidth: (text: string) => number;
+/**
+ * Makes provider output safe: keeps only SGR (and only when color is allowed), removes other
+ * escape sequences and control characters, tabs become spaces, non-ASCII becomes `?` when
+ * unicode is not allowed.
+ */
+export declare function sanitizeLine(line: string, options: {
+    color: boolean;
+    unicode: boolean;
+}): string;
+/** Truncates to `width` columns, keeping SGR codes and resetting color when cut. */
+export declare function truncate(text: string, width: number, ellipsis?: string): string;
+export declare const padEnd: (text: string, width: number) => string;
+export declare const sgr: (enabled: boolean, open: string, close?: string) => (text: string) => string;
+export { SGR };

package/dist/startup/text.js

@@ -0,0 +1,68 @@
+/** Terminal text helpers for startup rendering (no pi-tui dependency). */
+const SGR = /\x1b\[[0-9;]*m/g;
+/** CSI, OSC, DCS/APC/PM/SOS strings and single-character escapes. */
+const CONTROL_SEQUENCE = /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[PX^_][^\x1b]*\x1b\\|\x1b[@-Z\\-_]/g;
+export const stripAnsi = (text) => text.replace(CONTROL_SEQUENCE, "");
+/** Printable width in columns (code points; wide East Asian glyphs count as one). */
+export const visibleWidth = (text) => [...stripAnsi(text)].length;
+const isAscii = (text) => /^[\x20-\x7e]*$/.test(text);
+/**
+ * Makes provider output safe: keeps only SGR (and only when color is allowed), removes other
+ * escape sequences and control characters, tabs become spaces, non-ASCII becomes `?` when
+ * unicode is not allowed.
+ */
+export function sanitizeLine(line, options) {
+    let out = "";
+    let last = 0;
+    const pieces = [];
+    for (const match of line.matchAll(CONTROL_SEQUENCE)) {
+        pieces.push({ text: line.slice(last, match.index), sgr: false });
+        pieces.push({ text: match[0], sgr: /^\x1b\[[0-9;]*m$/.test(match[0]) });
+        last = (match.index ?? 0) + match[0].length;
+    }
+    pieces.push({ text: line.slice(last), sgr: false });
+    for (const piece of pieces) {
+        if (piece.sgr) {
+            if (options.color)
+                out += piece.text;
+            continue;
+        }
+        if (piece.text.startsWith("\x1b"))
+            continue;
+        let text = piece.text.replace(/\t/g, "  ").replace(/[\x00-\x1f\x7f-\x9f]/g, "");
+        if (!options.unicode && !isAscii(text))
+            text = text.replace(/[^\x20-\x7e]/gu, "?");
+        out += text;
+    }
+    return out;
+}
+/** Truncates to `width` columns, keeping SGR codes and resetting color when cut. */
+export function truncate(text, width, ellipsis = "…") {
+    if (width <= 0)
+        return "";
+    if (visibleWidth(text) <= width)
+        return text;
+    const room = Math.max(0, width - [...ellipsis].length);
+    let out = "", used = 0, colored = false;
+    for (const token of text.split(/(\x1b\[[0-9;]*m)/)) {
+        if (!token)
+            continue;
+        if (/^\x1b\[[0-9;]*m$/.test(token)) {
+            out += token;
+            colored = true;
+            continue;
+        }
+        for (const ch of token) {
+            if (used >= room)
+                break;
+            out += ch;
+            used++;
+        }
+        if (used >= room)
+            break;
+    }
+    return `${out}${ellipsis.slice(0, width - used)}${colored ? "\x1b[0m" : ""}`;
+}
+export const padEnd = (text, width) => `${text}${" ".repeat(Math.max(0, width - visibleWidth(text)))}`;
+export const sgr = (enabled, open, close = "0") => (text) => enabled ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+export { SGR };

package/dist/tools/execute.d.ts

@@ -0,0 +1,16 @@
+import type { Policy } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+export declare const EXECUTE_TIMEOUT_MS = 10000;
+export declare const MAX_NESTED_CALLS = 20;
+export interface ExecuteDeps {
+    registry: ToolRegistry;
+    policy: Policy;
+    workspace: string;
+    signal: AbortSignal;
+    emit: (data: unknown) => void;
+    session?: string;
+    label?: string;
+    /** Overrides `EXECUTE_TIMEOUT_MS`, mainly for tests. */
+    timeoutMs?: number;
+}
+export declare function runExecute(code: string, deps: ExecuteDeps): Promise<unknown>;

package/dist/tools/execute.js

@@ -0,0 +1,96 @@
+/**
+ * `execute` ("Code Mode"): runs a short JS snippet that can call other already-registered tools,
+ * so the model combines/post-processes several tool calls without every intermediate result
+ * re-entering its own context — only the snippet's final return value does.
+ *
+ * Honest scope, matching AGENTS.md's rule to never treat a subprocess or manifest as a sandbox:
+ * this uses Node's `vm` module, which gives the snippet its own global object and V8 intrinsics
+ * (no `require`, `process`, `fetch`, filesystem or timers unless explicitly added — and none are
+ * added here), but it is **not a security boundary**. Node's own documentation is explicit about
+ * this: "the vm module is not a security mechanism; do not use it to run untrusted code." A
+ * sufficiently motivated attacker with V8 exploits, or a lucky garbage-collection timing bug,
+ * could still escape it. It is a correctness/ergonomics sandbox (isolate a snippet's scope,
+ * bound its running time, keep it from importing or shelling out directly), not an OS-level
+ * one — the same trust model as the rest of Alisio's in-process tools.
+ *
+ * Nested tool calls run through the exact same effect/permission gate every other call uses (see
+ * `allowedEffect`): a snippet can only reach a tool whose effect the current policy already
+ * allows. It never gets to trigger a NEW interactive approval prompt from inside the sandbox —
+ * that would risk a confusing, potentially deadlocking nested prompt — so an effect that would
+ * otherwise need approval is denied outright here, never silently granted.
+ */
+import { createContext, Script } from "node:vm";
+export const EXECUTE_TIMEOUT_MS = 10_000;
+export const MAX_NESTED_CALLS = 20;
+const allowedEffect = (policy, effect) => effect === "read" || effect === "internal" || !!policy[effect];
+export async function runExecute(code, deps) {
+    let calls = 0;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(deps.signal.reason);
+    if (deps.signal.aborted)
+        controller.abort(deps.signal.reason);
+    else
+        deps.signal.addEventListener("abort", onAbort, { once: true });
+    const nestedSignal = AbortSignal.any([deps.signal, controller.signal]);
+    const callTool = async (name, input) => {
+        if (typeof name !== "string" || !name)
+            throw new Error("callTool: name must be a non-empty string");
+        if (name === "execute")
+            throw new Error("callTool: execute cannot call itself");
+        calls++;
+        if (calls > MAX_NESTED_CALLS)
+            throw new Error(`callTool: exceeded the limit of ${MAX_NESTED_CALLS} nested tool calls`);
+        const tool = deps.registry.get(name); // throws "Unknown tool: <name>" when absent
+        const effect = tool.effect ?? "external";
+        if (!allowedEffect(deps.policy, effect))
+            throw new Error(`callTool: capability denied for "${name}" (effect: ${effect}); execute cannot request ` +
+                "new approvals, only use capabilities already allowed for this session");
+        const rawInput = input && typeof input === "object" ? input : {};
+        const validated = deps.registry.parse(name, JSON.stringify(rawInput));
+        const result = await tool.execute(validated, {
+            signal: nestedSignal,
+            workspace: deps.workspace,
+            emit: deps.emit,
+            ...(deps.session ? { session: deps.session } : {}),
+            ...(deps.label ? { label: deps.label } : {}),
+        });
+        const text = result.content.map((c) => c.text).join("\n");
+        if (result.isError)
+            throw new Error(text);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    };
+    // A fresh V8 context: its own global object and intrinsics, no Node globals injected (no
+    // `require`, `process`, `Buffer`, `fetch`, `setTimeout`) — only `callTool` is exposed.
+    const context = createContext({ callTool }, { codeGeneration: { strings: false, wasm: false } });
+    let script;
+    try {
+        script = new Script(`"use strict";\n(async () => {\n${code}\n})()`, {
+            filename: "execute-snippet.js",
+        });
+    }
+    catch (error) {
+        throw new Error(`execute: snippet has a syntax error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const timeoutMs = deps.timeoutMs ?? EXECUTE_TIMEOUT_MS;
+    const timeout = new Promise((_, reject) => {
+        const timer = setTimeout(() => {
+            controller.abort(new Error("execute: timed out"));
+            reject(new Error(`execute: snippet exceeded ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+    });
+    try {
+        // `timeout` here only bounds the SYNCHRONOUS portion of starting the async function; the
+        // outer `timeout` promise above is what actually bounds the awaited nested tool calls.
+        const resultPromise = script.runInContext(context, { timeout: timeoutMs });
+        return await Promise.race([resultPromise, timeout]);
+    }
+    finally {
+        deps.signal.removeEventListener("abort", onAbort);
+    }
+}

package/dist/tools/search.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Pluggable web-search backends for the `websearch` standard tool. No provider is bundled as a
+ * hard dependency: everything here is a plain HTTP call behind the SDK's `SearchProvider` port.
+ *
+ * Resolution order (see `searchWithFallback`):
+ *   1. A plugin-registered `websearch` extension (`api.extensions.register("websearch", ...)`)
+ *      fully replaces the built-in chain, exactly like a custom mascot replaces the default one.
+ *      A throwing plugin provider falls back to the built-in chain with a diagnostic, never a hard
+ *      failure of the tool call.
+ *   2. `websearch.provider` from config, when set: `"searxng"` (with a custom `searxngUrl`),
+ *      `"duckduckgo-instant"`, `"tavily"`, `"brave"` or `"serpapi"` (the last three need an API key
+ *      env var).
+ *   3. Nothing configured: a public SearXNG instance (see `DEFAULT_SEARXNG_URL`) — genuinely free
+ *      and keyless, but empirically unreliable: while building this tool, nearly every public
+ *      instance tried (searx.be and several others from https://searx.space) rate-limited or
+ *      bot-blocked a single fresh automated request. Treat this as a zero-config starting point
+ *      to try, not something to depend on; self-hosting is one config line away
+ *      (`websearch.searxngUrl`, e.g. `docker run searxng/searxng`).
+ *
+ * `"native"` is resolved one layer up (see `application.ts`): when configured, the `websearch`
+ * tool is not registered at all, because the provider answers the search server-side as part of
+ * its own response, never through this tool-execution path.
+ */
+import type { SearchProvider, SearchResult } from "@alisio/sdk";
+export interface WebsearchConfig {
+    provider?: "searxng" | "duckduckgo-instant" | "tavily" | "brave" | "serpapi" | "native";
+    /** Overrides the default public instance; self-hosted or another public instance. */
+    searxngUrl?: string;
+    /** Environment variable holding the API key for `tavily`, `brave` or `serpapi`. */
+    apiKeyEnv?: string;
+}
+/**
+ * A long-running, widely mirrored public SearXNG instance (see https://searx.space for others).
+ * Best-effort only: a public instance has no SLA and routinely rate-limits or bot-blocks
+ * automated requests (verified empirically — see the module doc comment above).
+ */
+export declare const DEFAULT_SEARXNG_URL = "https://searx.be";
+/**
+ * Heuristic SSRF guard: a user-configured `searxngUrl` could point anywhere, unlike the fixed
+ * built-in providers' hardcoded hosts. This is not exhaustive (no DNS-rebinding protection), but
+ * it rejects the obvious cases and requires HTTPS for anything that is not clearly local/private.
+ */
+export declare function isLoopbackOrPrivateHost(hostname: string): boolean;
+export declare function validateSearxngUrl(raw: string): URL;
+export declare function searxngProvider(baseUrl: string): SearchProvider;
+/**
+ * DuckDuckGo's free, keyless Instant Answer API. It only returns a result for a direct
+ * factual/infobox-style query (Wikipedia-style); an ordinary "search the web for X" query
+ * routinely returns nothing here even though results exist on the web — this is NOT a general
+ * search engine. Callers must not treat an empty result as "nothing found on the web".
+ */
+export declare function duckDuckGoInstantProvider(): SearchProvider;
+export declare function tavilyProvider(apiKey: string): SearchProvider;
+export declare function braveProvider(apiKey: string): SearchProvider;
+export declare function serpApiProvider(apiKey: string): SearchProvider;
+export interface ResolvedSearch {
+    provider: SearchProvider;
+    source: string;
+    limitation?: string;
+}
+export interface SearchOutcome extends ResolvedSearch {
+    results: SearchResult[];
+    /** Set only when a plugin-registered provider failed and the built-in chain served instead. */
+    diagnostic?: string;
+}
+export declare function searchWithFallback(query: string, config: WebsearchConfig | undefined, resolveExtension: (() => {
+    provider: SearchProvider;
+    plugin: string;
+} | undefined) | undefined, signal: AbortSignal): Promise<SearchOutcome>;