@alisio/core 0.1.0-alpha.3

package/dist/tools/search.js

@@ -0,0 +1,232 @@
+/**
+ * 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 const DEFAULT_SEARXNG_URL = "https://searx.be";
+const PRIVATE_IPV4 = [
+    /^127\./,
+    /^10\./,
+    /^192\.168\./,
+    /^172\.(1[6-9]|2\d|3[0-1])\./,
+    /^169\.254\./,
+];
+/**
+ * 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 function isLoopbackOrPrivateHost(hostname) {
+    const h = hostname.toLowerCase();
+    if (h === "localhost" || h === "::1" || h === "[::1]")
+        return true;
+    if (PRIVATE_IPV4.some((re) => re.test(h)))
+        return true;
+    if (h.startsWith("fc") || h.startsWith("fd"))
+        return true; // IPv6 unique local addresses
+    return false;
+}
+export function validateSearxngUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`websearch.searxngUrl is not a valid URL: ${raw}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("websearch.searxngUrl must be http or https");
+    if (url.protocol === "http:" && !isLoopbackOrPrivateHost(url.hostname))
+        throw new Error("websearch.searxngUrl must use https unless it targets a loopback or private host");
+    return url;
+}
+const asText = (value) => (typeof value === "string" ? value : "");
+// Some public search backends (DuckDuckGo's Instant Answer API among them) vary their response
+// content-type by User-Agent; a browser-like one gets consistent JSON instead of a JSONP-flavored
+// content-type for an unrecognized client.
+const DEFAULT_UA = "Mozilla/5.0 (compatible; AlisioAgent/1.0; +https://github.com/GustavoGutierrez/alisio)";
+async function getJson(url, options) {
+    const res = await fetch(url, {
+        signal: options.signal,
+        headers: { "User-Agent": DEFAULT_UA, ...options.headers },
+    });
+    if (!res.ok)
+        throw new Error(`${url.hostname} search request failed: HTTP ${res.status}`);
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // A public SearXNG instance under bot protection answers 200 with an HTML challenge/captcha
+        // page instead of JSON (some APIs, like DuckDuckGo's, also report a non-JSON content-type on
+        // an otherwise-valid JSON body, so content-type alone cannot tell the two apart). A plain
+        // `res.json()` call would fail here with a confusing "Unexpected token '<'"; this gives the
+        // actual, actionable cause instead.
+        throw new Error(`${url.hostname} did not return valid JSON; it may be showing a bot-check/captcha page ` +
+            "instead of results. Public instances vary in how aggressively they block automated " +
+            "requests — try another instance or self-host one (see websearch.searxngUrl, e.g. " +
+            '"http://localhost:8080").');
+    }
+}
+export function searxngProvider(baseUrl) {
+    const validated = validateSearxngUrl(baseUrl);
+    return {
+        id: `searxng:${validated.host}`,
+        async search(query, options) {
+            const url = new URL("/search", validated);
+            url.searchParams.set("q", query);
+            url.searchParams.set("format", "json");
+            const body = (await getJson(url, { signal: options?.signal }));
+            return (body.results ?? [])
+                .slice(0, 10)
+                .map((r) => ({ title: asText(r.title), url: asText(r.url), snippet: asText(r.content) }));
+        },
+    };
+}
+/**
+ * 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 function duckDuckGoInstantProvider() {
+    return {
+        id: "duckduckgo-instant",
+        async search(query, options) {
+            const url = new URL("https://api.duckduckgo.com/");
+            url.searchParams.set("q", query);
+            url.searchParams.set("format", "json");
+            url.searchParams.set("no_html", "1");
+            url.searchParams.set("skip_disambig", "1");
+            const body = (await getJson(url, { signal: options?.signal }));
+            const results = [];
+            if (asText(body.AbstractText))
+                results.push({
+                    title: asText(body.Heading) || query,
+                    url: asText(body.AbstractURL),
+                    snippet: asText(body.AbstractText),
+                });
+            for (const topic of body.RelatedTopics ?? []) {
+                const text = asText(topic.Text);
+                const link = asText(topic.FirstURL);
+                if (text && link)
+                    results.push({ title: text.split(" - ")[0] || text, url: link, snippet: text });
+            }
+            return results.slice(0, 10);
+        },
+    };
+}
+export function tavilyProvider(apiKey) {
+    return {
+        id: "tavily",
+        async search(query, options) {
+            const res = await fetch("https://api.tavily.com/search", {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "User-Agent": DEFAULT_UA },
+                body: JSON.stringify({ api_key: apiKey, query, max_results: 10 }),
+                signal: options?.signal,
+            });
+            if (!res.ok)
+                throw new Error(`Tavily search request failed: HTTP ${res.status}`);
+            const body = (await res.json());
+            return (body.results ?? []).map((r) => ({
+                title: asText(r.title),
+                url: asText(r.url),
+                snippet: asText(r.content),
+            }));
+        },
+    };
+}
+export function braveProvider(apiKey) {
+    return {
+        id: "brave",
+        async search(query, options) {
+            const url = new URL("https://api.search.brave.com/res/v1/web/search");
+            url.searchParams.set("q", query);
+            const body = (await getJson(url, {
+                signal: options?.signal,
+                headers: { "X-Subscription-Token": apiKey, Accept: "application/json" },
+            }));
+            return (body.web?.results ?? []).map((r) => ({
+                title: asText(r.title),
+                url: asText(r.url),
+                snippet: asText(r.description),
+            }));
+        },
+    };
+}
+export function serpApiProvider(apiKey) {
+    return {
+        id: "serpapi",
+        async search(query, options) {
+            const url = new URL("https://serpapi.com/search.json");
+            url.searchParams.set("q", query);
+            url.searchParams.set("api_key", apiKey);
+            const body = (await getJson(url, { signal: options?.signal }));
+            return (body.organic_results ?? []).map((r) => ({
+                title: asText(r.title),
+                url: asText(r.link),
+                snippet: asText(r.snippet),
+            }));
+        },
+    };
+}
+function resolveBuiltin(config) {
+    const provider = config?.provider;
+    if (!provider || provider === "searxng") {
+        const url = config?.searxngUrl ?? DEFAULT_SEARXNG_URL;
+        return {
+            provider: searxngProvider(url),
+            source: config?.searxngUrl ? `searxng (${url})` : `default public SearXNG instance (${url})`,
+            ...(config?.searxngUrl
+                ? {}
+                : {
+                    limitation: "Using a public SearXNG instance. In practice, most public instances rate-limit " +
+                        "or bot-block a fresh automated request (verified while building this tool: " +
+                        "nearly every instance tried returned 429 or a captcha page on the first call) — " +
+                        "treat this as a best-effort starting point, not a reliable default. Self-host " +
+                        "(e.g. `docker run searxng/searxng`) and set websearch.searxngUrl (for example " +
+                        '"http://localhost:8080") for search that actually works consistently.',
+                }),
+        };
+    }
+    if (provider === "duckduckgo-instant")
+        return {
+            provider: duckDuckGoInstantProvider(),
+            source: "duckduckgo-instant",
+            limitation: "DuckDuckGo's Instant Answer API only answers direct factual/infobox-style queries, not " +
+                "general web search. An empty result here does not mean nothing exists on the web.",
+        };
+    if (provider === "native")
+        throw new Error('websearch.provider is "native": search runs server-side through the model provider; ' +
+            "this tool should never be registered or called in that mode.");
+    const envVar = config?.apiKeyEnv ?? `${provider.toUpperCase()}_API_KEY`;
+    const key = process.env[envVar];
+    if (!key)
+        throw new Error(`websearch.provider is "${provider}" but ${envVar} is not set in the environment`);
+    if (provider === "tavily")
+        return { provider: tavilyProvider(key), source: "tavily" };
+    if (provider === "brave")
+        return { provider: braveProvider(key), source: "brave" };
+    if (provider === "serpapi")
+        return { provider: serpApiProvider(key), source: "serpapi" };
+    throw new Error(`Unknown websearch.provider: ${provider}`);
+}
+export async function searchWithFallback(query, config, resolveExtension, signal) {
+    const extension = resolveExtension?.();
+    if (extension) {
+        try {
+            const results = await extension.provider.search(query, { signal });
+            return { provider: extension.provider, source: `plugin:${extension.plugin}`, results };
+        }
+        catch (error) {
+            const diagnostic = `Plugin websearch provider (${extension.plugin}) failed, using the built-in chain instead: ${error instanceof Error ? error.message : String(error)}`;
+            const builtin = resolveBuiltin(config);
+            const results = await builtin.provider.search(query, { signal });
+            return { ...builtin, results, diagnostic };
+        }
+    }
+    const builtin = resolveBuiltin(config);
+    const results = await builtin.provider.search(query, { signal });
+    return { ...builtin, results };
+}

package/dist/tools/standard.d.ts

@@ -0,0 +1,22 @@
+import { type AskQuestionsRequest, type AskQuestionsResult, type JsonSchema, type SearchProvider } from "@alisio/sdk";
+import type { Policy } from "../core/contracts.ts";
+import type { ToolRegistry } from "../core/registry.ts";
+import type { ProjectContext } from "../resources/context.ts";
+import type { Skills } from "../resources/skills.ts";
+import { type WebsearchConfig } from "./search.ts";
+export declare const objectSchema: (properties: Record<string, unknown>, required?: string[]) => JsonSchema;
+export declare const hash: (text: string) => string;
+export declare function registerStandard(registry: ToolRegistry, workspace: string, skills: Skills, context: ProjectContext, ui?: {
+    interactive(): boolean;
+    askQuestions(request: AskQuestionsRequest): Promise<AskQuestionsResult>;
+}, 
+/** Live policy accessor for `execute`'s nested tool calls (bound once the runner exists). */
+execCtx?: {
+    policy(): Policy;
+}, websearchCtx?: {
+    config?: WebsearchConfig;
+    resolveExtension?: () => {
+        provider: SearchProvider;
+        plugin: string;
+    } | undefined;
+}): void;

package/dist/tools/standard.js

@@ -0,0 +1,408 @@
+import { createHash } from "node:crypto";
+import { mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, relative } from "node:path";
+import { textResult, } from "@alisio/sdk";
+import { fileSize, readHead, readText } from "../runtime/fs.js";
+import { safePath } from "../runtime/paths.js";
+import { runProcess } from "../runtime/process.js";
+import { EXECUTE_TIMEOUT_MS, MAX_NESTED_CALLS, runExecute } from "./execute.js";
+import { searchWithFallback } from "./search.js";
+import { DEFAULT_TIMEOUT_SECONDS, MAX_RESPONSE_BYTES, MAX_TIMEOUT_SECONDS, webfetch, } from "./webfetch.js";
+const str = { type: "string" }, integer = { type: "integer", minimum: 0 };
+export const objectSchema = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+export const hash = (text) => createHash("sha256").update(text).digest("hex");
+async function existing(path) {
+    const size = await fileSize(path);
+    if (size === undefined)
+        return;
+    if (size > 1_048_576)
+        throw new Error("Editable files are limited to 1 MiB");
+    return readText(path);
+}
+async function atomicWrite(root, path, content, expected) {
+    path = await safePath(root, path);
+    await mkdir(dirname(path), { recursive: true });
+    const before = await existing(path);
+    if (before === undefined ? expected !== null : hash(before) !== expected)
+        throw new Error("File precondition failed: reread the file and use its current sha256");
+    const temporary = `${path}.alisio-${crypto.randomUUID()}.tmp`;
+    try {
+        const mode = before === undefined ? 0o644 : (await stat(path)).mode & 0o777;
+        await writeFile(temporary, content, { mode });
+        await safePath(root, path);
+        const now = await existing(path);
+        if (now !== before)
+            throw new Error("File changed while preparing write");
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+export function registerStandard(registry, workspace, skills, context, ui, 
+/** Live policy accessor for `execute`'s nested tool calls (bound once the runner exists). */
+execCtx, websearchCtx) {
+    const register = (tool) => registry.register(tool);
+    const filePaths = (input) => typeof input.path === "string" ? [input.path] : [];
+    register({
+        name: "read_file",
+        effect: "read",
+        description: "Read UTF-8 text by line; returns sha256 for safe edits. Max scan 1 MiB.",
+        inputSchema: objectSchema({
+            path: str,
+            startLine: { type: "integer", minimum: 1 },
+            limit: { type: "integer", minimum: 1, maximum: 1000 },
+        }, ["path"]),
+        paths: filePaths,
+        async execute(i, c) {
+            const path = await safePath(c.workspace, String(i.path));
+            const size = await fileSize(path);
+            if (size === undefined)
+                throw new Error(`File not found: ${String(i.path)}`);
+            const raw = await readHead(path, 1_048_576);
+            if (raw.includes("\0"))
+                throw new Error("Binary file; text reader refused");
+            const start = Number(i.startLine ?? 1), limit = Number(i.limit ?? 200), lines = raw.split("\n");
+            const content = lines
+                .slice(start - 1, start - 1 + limit)
+                .map((line, n) => `${start + n}: ${line}`)
+                .join("\n");
+            return textResult(JSON.stringify({
+                path: i.path,
+                sha256: size <= 1_048_576 ? hash(raw) : null,
+                startLine: start,
+                content: content.slice(0, 28_000),
+                truncated: size > 1_048_576 || start - 1 + limit < lines.length || content.length > 28_000,
+            }));
+        },
+    });
+    register({
+        name: "write_file",
+        effect: "write",
+        description: "Create or replace a file. expectedHash is null only for a new file, otherwise use read_file sha256.",
+        inputSchema: objectSchema({ path: str, content: str, expectedHash: { type: ["string", "null"] } }, ["path", "content", "expectedHash"]),
+        paths: filePaths,
+        async execute(i, c) {
+            const content = String(i.content);
+            if (Buffer.byteLength(content) > 1_048_576)
+                throw new Error("Write exceeds 1 MiB");
+            await atomicWrite(c.workspace, String(i.path), content, i.expectedHash);
+            return textResult(JSON.stringify({ path: i.path, sha256: hash(content) }));
+        },
+    });
+    register({
+        name: "edit_file",
+        effect: "write",
+        description: "Replace exactly one occurrence. Requires expectedHash from read_file; preserves untouched bytes and line endings.",
+        inputSchema: objectSchema({ path: str, oldText: { type: "string", minLength: 1 }, newText: str, expectedHash: str }, ["path", "oldText", "newText", "expectedHash"]),
+        paths: filePaths,
+        async execute(i, c) {
+            const path = await safePath(c.workspace, String(i.path)), before = await existing(path);
+            if (before === undefined)
+                throw new Error("File not found");
+            const needle = String(i.oldText), index = before.indexOf(needle);
+            if (index < 0 || before.indexOf(needle, index + 1) >= 0)
+                throw new Error("Edit must match exactly one occurrence");
+            const after = before.slice(0, index) + String(i.newText) + before.slice(index + needle.length);
+            await atomicWrite(c.workspace, path, after, String(i.expectedHash));
+            return textResult(JSON.stringify({ path: i.path, sha256: hash(after) }));
+        },
+    });
+    register({
+        name: "list_files",
+        effect: "read",
+        description: "List gitignore-aware files using ripgrep, paginated. Hidden files are excluded.",
+        inputSchema: objectSchema({
+            path: str,
+            offset: integer,
+            limit: { type: "integer", minimum: 1, maximum: 500 },
+        }),
+        paths: filePaths,
+        async execute(i, c) {
+            const path = await safePath(c.workspace, String(i.path ?? "."));
+            const result = await runProcess("rg", ["--files", "--glob", "!.git", "--glob", "!node_modules", "--", path], { cwd: c.workspace, signal: c.signal, maxBytes: 200_000 });
+            if (result.exitCode > 1 && !result.truncated)
+                throw new Error(result.stderr);
+            const all = result.stdout
+                .trim()
+                .split("\n")
+                .filter(Boolean)
+                .map((p) => relative(c.workspace, p))
+                .sort(), offset = Number(i.offset ?? 0), limit = Number(i.limit ?? 100);
+            return textResult(JSON.stringify({
+                files: all.slice(offset, offset + limit),
+                nextOffset: offset + limit < all.length ? offset + limit : null,
+                truncated: result.truncated,
+            }));
+        },
+    });
+    register({
+        name: "search_text",
+        effect: "read",
+        description: "Search text using ripgrep regex, JSON results and bounded output; exit code 1 means no matches.",
+        inputSchema: objectSchema({ pattern: str, path: str, literal: { type: "boolean" } }, [
+            "pattern",
+        ]),
+        paths: filePaths,
+        async execute(i, c) {
+            const path = await safePath(c.workspace, String(i.path ?? "."));
+            const r = await runProcess("rg", [
+                "--json",
+                "--max-count",
+                "100",
+                "--glob",
+                "!.git",
+                "--glob",
+                "!node_modules",
+                ...(i.literal ? ["--fixed-strings"] : []),
+                "--",
+                String(i.pattern),
+                path,
+            ], { cwd: c.workspace, signal: c.signal });
+            if (r.exitCode > 1 && !r.truncated)
+                throw new Error(r.stderr);
+            return textResult(JSON.stringify(r));
+        },
+    });
+    register({
+        name: "run_process",
+        effect: "process",
+        description: "Run an executable with an argument array. Not sandboxed; may access outside workspace.",
+        inputSchema: objectSchema({
+            command: str,
+            args: { type: "array", items: str },
+            timeoutMs: { type: "integer", minimum: 1, maximum: 120000 },
+        }, ["command", "args"]),
+        async execute(i, c) {
+            return textResult(JSON.stringify(await runProcess(String(i.command), i.args, {
+                cwd: c.workspace,
+                signal: c.signal,
+                timeoutMs: Number(i.timeoutMs ?? 30000),
+                onData: c.emit,
+            })));
+        },
+    });
+    register({
+        name: "shell",
+        effect: "process",
+        description: "Run an arbitrary shell command. Explicit process capability required; not sandboxed.",
+        inputSchema: objectSchema({ command: str }, ["command"]),
+        async execute(i, c) {
+            return textResult(JSON.stringify(await runProcess(process.platform === "win32" ? "cmd.exe" : "/bin/sh", process.platform === "win32"
+                ? ["/d", "/s", "/c", String(i.command)]
+                : ["-c", String(i.command)], { cwd: c.workspace, signal: c.signal, onData: c.emit })));
+        },
+    });
+    for (const [name, args] of [
+        ["git_status", ["status", "--porcelain=v1"]],
+        ["git_diff", ["diff", "--no-ext-diff", "--no-textconv"]],
+    ])
+        register({
+            name,
+            effect: "read",
+            description: `Read ${name} without mutating the repository.`,
+            inputSchema: objectSchema({}),
+            async execute(_i, c) {
+                const r = await runProcess("git", ["--no-pager", ...args], {
+                    cwd: c.workspace,
+                    signal: c.signal,
+                });
+                if (r.exitCode !== 0)
+                    throw new Error(r.stderr);
+                return textResult(JSON.stringify(r));
+            },
+        });
+    register({
+        name: "skill_load",
+        effect: "read",
+        description: "Load a skill's full instructions on demand.",
+        inputSchema: objectSchema({ name: str }, ["name"]),
+        async execute(i) {
+            return textResult(await skills.load(String(i.name)));
+        },
+    });
+    register({
+        name: "skill_search",
+        effect: "read",
+        description: "Search available skill metadata.",
+        inputSchema: objectSchema({ query: str }, ["query"]),
+        async execute(i) {
+            const q = String(i.query).toLowerCase();
+            return textResult(JSON.stringify([...skills.items.values()]
+                .filter((s) => `${s.name} ${s.description}`.toLowerCase().includes(q))
+                .slice(0, 30)));
+        },
+    });
+    register({
+        name: "skill_resource",
+        effect: "read",
+        description: "Read a supporting file relative to a skill root.",
+        inputSchema: objectSchema({ name: str, path: str }, ["name", "path"]),
+        async execute(i) {
+            return textResult(await skills.resource(String(i.name), String(i.path)));
+        },
+    });
+    register({
+        name: "context_explain",
+        effect: "read",
+        description: "Inspect scoped AGENTS.md for a target file.",
+        inputSchema: objectSchema({ path: str }, ["path"]),
+        paths: filePaths,
+        async execute(i) {
+            return textResult(JSON.stringify(await context.explain(String(i.path))));
+        },
+    });
+    register({
+        name: "ask_user_question",
+        effect: "read",
+        description: "Ask the user one or more multiple-choice questions when there is a real fork in the " +
+            "approach and their preference genuinely changes what you do next. Each question needs 2-4 " +
+            "concrete options; mark at most one `recommended` when you have a clear opinion, but it is " +
+            "only a suggestion, never forced on the user. Prefer a single round: only ask a follow-up " +
+            "batch afterward if the answers create a genuinely new fork. Only usable in an interactive " +
+            "session; if it is not, this call fails and you should ask the question in plain text instead " +
+            "and wait for the user's normal reply.",
+        inputSchema: objectSchema({
+            questions: {
+                type: "array",
+                minItems: 1,
+                maxItems: 4,
+                items: {
+                    type: "object",
+                    properties: {
+                        header: { type: "string", minLength: 1, maxLength: 40 },
+                        question: { type: "string", minLength: 1 },
+                        multiSelect: { type: "boolean" },
+                        options: {
+                            type: "array",
+                            minItems: 2,
+                            maxItems: 4,
+                            items: objectSchema({
+                                label: { type: "string", minLength: 1 },
+                                description: str,
+                                recommended: { type: "boolean" },
+                            }, ["label"]),
+                        },
+                    },
+                    required: ["header", "question", "options"],
+                    additionalProperties: false,
+                },
+            },
+        }, ["questions"]),
+        async execute(i, c) {
+            if (!ui?.interactive())
+                return textResult(JSON.stringify({
+                    error: "ask_user_question is unavailable: this session is not interactive (headless or " +
+                        "--json). Ask the question in plain text in your reply instead and wait for the " +
+                        "user's normal answer; never rely on this tool here.",
+                }), true);
+            const specs = i.questions;
+            for (const spec of specs) {
+                const recommended = spec.options.filter((o) => o.recommended).length;
+                if (recommended > 1)
+                    throw new Error(`At most one option may be recommended (question "${spec.header}")`);
+                const labels = new Set(spec.options.map((o) => o.label));
+                if (labels.size !== spec.options.length)
+                    throw new Error(`Option labels must be unique within a question ("${spec.header}")`);
+            }
+            const questions = specs.map((spec, index) => ({
+                id: `q${index}`,
+                header: spec.header,
+                question: spec.question,
+                multiSelect: spec.multiSelect,
+                options: spec.options.map((o) => ({
+                    value: o.label,
+                    label: o.label,
+                    ...(o.description ? { description: o.description } : {}),
+                    ...(o.recommended ? { recommended: true } : {}),
+                })),
+            }));
+            const result = await ui.askQuestions({
+                questions,
+                ...(c.session ? { session: c.session } : {}),
+                ...(c.label ? { label: c.label } : {}),
+                signal: c.signal,
+            });
+            const answers = specs.map((spec, index) => {
+                const value = result[`q${index}`];
+                if (value === undefined)
+                    return { header: spec.header, skipped: true, selected: [] };
+                return {
+                    header: spec.header,
+                    skipped: false,
+                    selected: Array.isArray(value) ? value : [value],
+                };
+            });
+            return textResult(JSON.stringify({ answers }));
+        },
+    });
+    register({
+        name: "webfetch",
+        effect: "external",
+        description: "Fetch a URL as text, markdown or HTML (default markdown). Follows redirects; refuses " +
+            `binary/image responses; capped at ${MAX_RESPONSE_BYTES} bytes. Long pages are truncated ` +
+            "in the result with a `fullTextPath` you can read in full with read_file.",
+        inputSchema: objectSchema({
+            url: str,
+            format: { type: "string", enum: ["markdown", "text", "html"] },
+            timeout: {
+                type: "integer",
+                minimum: 1,
+                maximum: MAX_TIMEOUT_SECONDS,
+                description: "Seconds, default 30, capped at 120",
+            },
+        }, ["url"]),
+        async execute(i, c) {
+            const result = await webfetch(c.workspace, String(i.url), i.format ?? "markdown", Number(i.timeout ?? DEFAULT_TIMEOUT_SECONDS), c.signal);
+            return textResult(JSON.stringify(result));
+        },
+    });
+    // In "native" mode the provider answers search server-side (see application.ts); registering
+    // this tool too would just confuse the model with a second, redundant search path.
+    if (websearchCtx?.config?.provider !== "native")
+        register({
+            name: "websearch",
+            effect: "external",
+            description: "Search the web and return {title, url, snippet} results. Uses a configured provider " +
+                "(websearch.provider in config), or a public SearXNG instance by default; check the " +
+                "result's `limitation` field, since some providers (e.g. duckduckgo-instant) only answer " +
+                "direct factual queries, not general search.",
+            inputSchema: objectSchema({ query: { type: "string", minLength: 1 } }, ["query"]),
+            async execute(i, c) {
+                const outcome = await searchWithFallback(String(i.query), websearchCtx?.config, websearchCtx?.resolveExtension, c.signal);
+                return textResult(JSON.stringify({
+                    results: outcome.results,
+                    source: outcome.source,
+                    ...(outcome.limitation ? { limitation: outcome.limitation } : {}),
+                    ...(outcome.diagnostic ? { diagnostic: outcome.diagnostic } : {}),
+                }));
+            },
+        });
+    register({
+        name: "execute",
+        effect: "process",
+        description: "Run a short JavaScript snippet (Code Mode) that can call other tools via " +
+            "`await callTool(name, input)` and return one final JSON-serializable value, so " +
+            "intermediate tool results never re-enter your context — only the return value does. " +
+            "The snippet runs in an isolated context with no filesystem, network, imports or timers " +
+            "of its own; every nested callTool still goes through this session's normal permission " +
+            `gate (an effect not already allowed is denied, never newly approved). Bounded to ` +
+            `${EXECUTE_TIMEOUT_MS}ms wall-clock and ${MAX_NESTED_CALLS} nested tool calls. This is a ` +
+            "correctness sandbox, not an OS security boundary. Prefer plain sequential tool calls " +
+            "unless you are combining several read-only calls or post-processing their output.",
+        inputSchema: objectSchema({ code: { type: "string", minLength: 1 } }, ["code"]),
+        async execute(i, c) {
+            const policy = execCtx?.policy() ?? { write: false, process: false, external: false };
+            const result = await runExecute(String(i.code), {
+                registry,
+                policy,
+                workspace: c.workspace,
+                signal: c.signal,
+                emit: c.emit,
+                ...(c.session ? { session: c.session } : {}),
+                ...(c.label ? { label: c.label } : {}),
+            });
+            return textResult(JSON.stringify({ result: result ?? null }));
+        },
+    });
+}