nexus-ai-pro 2.5.0 → 2.7.0

package/dist/agent/sandbox-container.js

@@ -0,0 +1,291 @@
+import { GREP_FILE_BYTES, GREP_TOTAL_BYTES, globMatcher, matchingLines, WALK_LIMIT } from './glob.js';
+import { SandboxPathError, } from './sandbox.js';
+export function containerSandbox(options) {
+    const binary = options.binary ?? 'docker';
+    const workdir = `/${(options.workdir ?? '/workspace').replace(/^\/+|\/+$/g, '')}`;
+    const maxOutput = options.maxOutputBytes ?? 1_048_576;
+    const network = options.network ?? false;
+    const label = `nexus-sandbox-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    let marks = 0;
+    const inside = (file) => {
+        const unified = file.replace(/\\/g, '/');
+        if (unified.includes('\0'))
+            throw new SandboxPathError(file);
+        const parts = [];
+        for (const segment of (unified.startsWith('/') ? unified : `${workdir}/${unified}`).split('/')) {
+            if (segment === '' || segment === '.')
+                continue;
+            if (segment !== '..')
+                parts.push(segment);
+            else if (parts.pop() === undefined)
+                throw new SandboxPathError(file);
+        }
+        const resolved = `/${parts.join('/')}`;
+        if (resolved !== workdir && !resolved.startsWith(`${workdir}/`))
+            throw new SandboxPathError(file);
+        return resolved;
+    };
+    const fromRoot = (path) => (path === workdir ? '.' : path.slice(workdir.length + 1));
+    const invoke = async (args, call = {}) => {
+        const { spawn } = await import('node:child_process');
+        return new Promise((resolve) => {
+            const child = spawn(binary, args, { windowsHide: true });
+            const out = [];
+            let kept = 0;
+            let stderr = '';
+            let timedOut = false;
+            let settled = false;
+            child.stdout.on('data', (chunk) => {
+                const room = (call.keep ?? Number.POSITIVE_INFINITY) - kept;
+                if (room <= 0)
+                    return;
+                const part = chunk.byteLength > room ? chunk.subarray(0, room) : chunk;
+                out.push(part);
+                kept += part.byteLength;
+            });
+            child.stderr.on('data', (chunk) => {
+                if (stderr.length < maxOutput)
+                    stderr = (stderr + new TextDecoder().decode(chunk)).slice(0, maxOutput);
+            });
+            const stop = () => {
+                call.onStop?.();
+                child.kill('SIGKILL');
+            };
+            const timer = call.timeoutMs === undefined
+                ? undefined
+                : setTimeout(() => {
+                    timedOut = true;
+                    stop();
+                }, call.timeoutMs);
+            call.signal?.addEventListener('abort', stop, { once: true });
+            const finish = (code) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                call.signal?.removeEventListener('abort', stop);
+                resolve({ code: timedOut ? null : code, stdout: concat(out), stderr, timedOut });
+            };
+            child.on('error', (error) => {
+                stderr += error.message;
+                finish(null);
+            });
+            child.on('close', (code) => finish(code));
+            child.stdin.on('error', () => undefined);
+            child.stdin.end(call.stdin ?? '');
+        });
+    };
+    const failed = (what, result) => new Error(`${what} failed in the container: ${result.stderr.trim() || `exit code ${result.code}`}`);
+    let started;
+    const container = () => {
+        if (started)
+            return started;
+        const starting = (async () => {
+            const result = await invoke([
+                'run',
+                '--detach',
+                '--rm',
+                '--init',
+                '--name',
+                label,
+                '--label',
+                'nexus-ai-pro.sandbox=1',
+                '--workdir',
+                workdir,
+                ...(network === true ? [] : ['--network', network === false ? 'none' : network]),
+                '--memory',
+                options.memory ?? '512m',
+                '--memory-swap',
+                options.memory ?? '512m',
+                '--cpus',
+                String(options.cpus ?? 1),
+                '--pids-limit',
+                String(options.pids ?? 256),
+                '--cap-drop',
+                'ALL',
+                '--security-opt',
+                'no-new-privileges',
+                ...envArgs(options.env),
+                ...(options.runArgs ?? []),
+                '--entrypoint',
+                'tail',
+                options.image,
+                '-f',
+                '/dev/null',
+            ]);
+            if (result.code !== 0)
+                throw failed(`Starting ${options.image}`, result);
+            return new TextDecoder().decode(result.stdout).trim();
+        })();
+        started = starting;
+        starting.catch(() => {
+            if (started === starting)
+                started = undefined;
+        });
+        return starting;
+    };
+    const shell = async (script, args, stdin, keep) => {
+        const id = await container();
+        return invoke(['exec', ...(stdin === undefined ? [] : ['--interactive']), id, 'sh', '-c', script, 'sh', ...args], {
+            ...(stdin === undefined ? {} : { stdin }),
+            ...(keep === undefined ? {} : { keep }),
+        });
+    };
+    const walk = async (directory, filter = '') => {
+        const start = inside(directory);
+        const result = await shell(`find "$1" \\( -name .git -o -name node_modules \\) -prune -o -type f ${filter} -print`, [start]);
+        if (result.code !== 0 && result.stdout.byteLength === 0)
+            throw failed('Listing files', result);
+        return new TextDecoder()
+            .decode(result.stdout)
+            .split('\n')
+            .filter(Boolean)
+            .slice(0, WALK_LIMIT)
+            .map((path) => ({ fromRoot: fromRoot(path), fromStart: path.slice(start.length).replace(/^\//, '') }))
+            .sort((a, b) => (a.fromRoot < b.fromRoot ? -1 : a.fromRoot > b.fromRoot ? 1 : 0));
+    };
+    const readBytes = async (file) => {
+        const result = await shell('cat "$1"', [inside(file)]);
+        if (result.code !== 0)
+            throw failed(`Reading ${file}`, result);
+        return result.stdout;
+    };
+    return {
+        name: `container (${binary} ${options.image})`,
+        isolation: { filesystem: true, network: network === false, processes: true },
+        async exec(command, execOptions = {}) {
+            const id = await container();
+            const startedAt = Date.now();
+            const mark = `${label}-${++marks}`;
+            const result = await invoke([
+                'exec',
+                '--interactive',
+                '--workdir',
+                inside(execOptions.cwd ?? '.'),
+                ...envArgs({ ...options.env, ...execOptions.env, NEXUS_SANDBOX_EXEC: mark }),
+                id,
+                'sh',
+                '-c',
+                command,
+            ], {
+                stdin: execOptions.stdin ?? '',
+                keep: maxOutput,
+                timeoutMs: execOptions.timeoutMs ?? options.timeoutMs ?? 30_000,
+                ...(execOptions.signal ? { signal: execOptions.signal } : {}),
+                onStop: () => {
+                    void invoke(['exec', id, 'sh', '-c', KILL_MARKED, 'sh', mark]);
+                },
+            });
+            return {
+                exitCode: result.code,
+                stdout: new TextDecoder().decode(result.stdout),
+                stderr: result.stderr,
+                timedOut: result.timedOut,
+                durationMs: Date.now() - startedAt,
+            };
+        },
+        async readFile(file) {
+            return new TextDecoder().decode(await readBytes(file));
+        },
+        readBytes,
+        async writeFile(file, content) {
+            const result = await shell('mkdir -p "$(dirname "$1")" && cat > "$1"', [inside(file)], content);
+            if (result.code !== 0)
+                throw failed(`Writing ${file}`, result);
+        },
+        async listFiles(directory = '.') {
+            const result = await shell('ls -1A "$1"', [inside(directory)]);
+            if (result.code !== 0)
+                throw failed(`Listing ${directory}`, result);
+            return new TextDecoder().decode(result.stdout).split('\n').filter(Boolean).sort();
+        },
+        async removeFile(file) {
+            const target = inside(file);
+            if (target === workdir)
+                throw new SandboxPathError(file);
+            const result = await shell('rm -rf "$1"', [target]);
+            if (result.code !== 0)
+                throw failed(`Removing ${file}`, result);
+        },
+        async glob(pattern, globOptions = {}) {
+            const matches = globMatcher(pattern);
+            return (await walk(globOptions.cwd ?? '.'))
+                .filter((file) => matches(file.fromStart))
+                .slice(0, globOptions.limit ?? 1_000)
+                .map((file) => file.fromRoot);
+        },
+        async grep(pattern, grepOptions = {}) {
+            const expression = new RegExp(pattern, grepOptions.ignoreCase ? 'i' : '');
+            const only = grepOptions.glob ? globMatcher(grepOptions.glob) : undefined;
+            const limit = grepOptions.limit ?? 200;
+            const candidates = (await walk(grepOptions.cwd ?? '.', `-size -${GREP_FILE_BYTES / 1024 + 1}k`)).filter((file) => !only || only(file.fromStart));
+            const found = [];
+            let read = 0;
+            for (let index = 0; index < candidates.length && found.length < limit && read < GREP_TOTAL_BYTES; index += 200) {
+                const batch = candidates.slice(index, index + 200).map((file) => `./${file.fromRoot}`);
+                const result = await shell('cd "$1" && shift && tar -cf - "$@"', [workdir, ...batch], undefined, GREP_TOTAL_BYTES - read);
+                for (const entry of untar(result.stdout)) {
+                    read += entry.data.byteLength;
+                    const file = entry.name.replace(/^\.\//, '');
+                    found.push(...matchingLines(entry.data, expression, limit - found.length).map((match) => ({ file, ...match })));
+                    if (found.length >= limit)
+                        break;
+                }
+            }
+            return found;
+        },
+        async dispose() {
+            const current = started;
+            started = undefined;
+            const id = await current?.catch(() => undefined);
+            if (id)
+                await invoke(['rm', '--force', id]);
+        },
+    };
+}
+const KILL_MARKED = 'for p in /proc/[0-9]*; do if tr "\\000" "\\n" < "$p/environ" 2>/dev/null | grep -qx "NEXUS_SANDBOX_EXEC=$1"; then kill -9 "$(basename "$p")" 2>/dev/null; fi; done; true';
+function envArgs(env) {
+    return Object.entries(env ?? {}).flatMap(([key, value]) => ['--env', `${key}=${value}`]);
+}
+function concat(chunks) {
+    const bytes = new Uint8Array(chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function untar(tar) {
+    const decoder = new TextDecoder();
+    const field = (from, length) => {
+        const bytes = tar.subarray(from, from + length);
+        const end = bytes.indexOf(0);
+        return decoder.decode(end < 0 ? bytes : bytes.subarray(0, end));
+    };
+    const files = [];
+    let offset = 0;
+    let longName;
+    while (offset + 512 <= tar.byteLength) {
+        if (tar.subarray(offset, offset + 512).every((byte) => byte === 0))
+            break;
+        const size = Number.parseInt(field(offset + 124, 12).trim() || '0', 8);
+        const type = String.fromCharCode(tar[offset + 156] ?? 0);
+        const prefix = field(offset + 345, 155);
+        const name = longName ?? (prefix ? `${prefix}/${field(offset, 100)}` : field(offset, 100));
+        const data = tar.subarray(offset + 512, offset + 512 + size);
+        longName = undefined;
+        if (type === 'L') {
+            longName = decoder.decode(data).replace(/\0+$/, '');
+        }
+        else if (type === 'x') {
+            longName = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(decoder.decode(data))?.[1];
+        }
+        else if (type === '0' || type === '\0') {
+            files.push({ name, data });
+        }
+        offset += 512 + Math.ceil(size / 512) * 512;
+    }
+    return files;
+}

package/dist/agent/sandbox.d.ts

@@ -33,6 +33,33 @@ export interface SandboxExecResult {
     /** How long it ran, in milliseconds. */
     durationMs: number;
 }
+/** Options for `Sandbox.glob()`. */
+export interface SandboxGlobOptions {
+    /** The directory to search, inside the sandbox. Defaults to its root. */
+    cwd?: string;
+    /** The most paths returned. Defaults to 1,000. */
+    limit?: number;
+}
+/** Options for `Sandbox.grep()`. */
+export interface SandboxGrepOptions {
+    /** The directory to search, inside the sandbox. Defaults to its root. */
+    cwd?: string;
+    /** Searches only the files whose paths, relative to `cwd`, match this glob. */
+    glob?: string;
+    /** Matches without regard to case. */
+    ignoreCase?: boolean;
+    /** The most matching lines returned. Defaults to 200. */
+    limit?: number;
+}
+/** One line `Sandbox.grep()` matched. */
+export interface SandboxMatch {
+    /** The file, relative to the sandbox's root. */
+    file: string;
+    /** The line's number, counting from 1. */
+    line: number;
+    /** The line, cut to 300 characters. */
+    text: string;
+}
 /** What a sandbox claims to isolate. The conformance suite checks the claims it can observe. */
 export interface SandboxIsolation {
     /** Commands cannot read or write the host's files. */
@@ -58,6 +85,19 @@ export interface Sandbox {
     listFiles?(directory?: string): Promise<string[]>;
     /** Removes a file or directory. */
     removeFile?(file: string): Promise<void>;
+    /**
+     * The files under a directory whose paths match a glob, such as `src/**\/*.ts`, sorted. The glob
+     * matches paths relative to `cwd`; the paths returned are relative to the root, as `readFile`
+     * takes them. Returns at most `limit`.
+     */
+    glob?(pattern: string, options?: SandboxGlobOptions): Promise<string[]>;
+    /**
+     * The lines matching a regular expression in the files under a directory, at most `limit`. Large
+     * files and binary files are skipped.
+     */
+    grep?(pattern: string, options?: SandboxGrepOptions): Promise<SandboxMatch[]>;
+    /** Reads a file's bytes, for an image, audio, or a document. */
+    readBytes?(file: string): Promise<Uint8Array>;
     /** Releases the sandbox. */
     dispose?(): Promise<void>;
 }
@@ -88,14 +128,23 @@ export interface ProcessSandboxOptions {
  * Its file methods refuse any path outside `root`, and commands get only `PATH` and the variables
  * given, never the host's environment. But a command it runs can read and write anything the user
  * can, and reach any host: `isolation` says so. Use a container or a VM in production.
+ *
+ * Its search skips `.git` and `node_modules`, walks at most 20,000 entries, and follows no links;
+ * `grep()` skips files over 1 MB and binary files, reads at most 64 MB, and searches the first
+ * 4,000 characters of each line.
  */
 export declare function processSandbox(options: ProcessSandboxOptions): Sandbox;
 /** Options for `sandboxTools()`. */
 export interface SandboxToolsOptions {
     /** Offer `run_command`. Defaults to true. */
     shell?: boolean;
-    /** Offer `read_file`, `write_file`, and `list_files`. Defaults to true. */
+    /**
+     * Offer the file tools: `read_file`, `write_file`, and, where the sandbox can, `list_files`,
+     * `glob_files`, `grep_files`, and `read_media`. Defaults to true.
+     */
     files?: boolean;
+    /** The largest file `read_media` sends to the model, in bytes. Defaults to 10 MB. */
+    maxMediaBytes?: number;
     /**
      * The path a permission policy sees the sandbox's files under. Defaults to `/workspace`, so a
      * policy granting `/workspace/**` grants the sandbox.

package/dist/agent/sandbox.js

@@ -1,3 +1,5 @@
+import { encodeBase64 } from '../utils/base64.js';
+import { GREP_FILE_BYTES, GREP_TOTAL_BYTES, globMatcher, MEDIA_TYPES, matchingLines, SKIPPED_DIRECTORIES, WALK_LIMIT, } from './glob.js';
 export class SandboxPathError extends Error {
     path;
     code = 'SANDBOX_PATH';
@@ -9,7 +11,7 @@ export class SandboxPathError extends Error {
 }
 export function processSandbox(options) {
     const ready = (async () => {
-        const [{ spawn }, fs, { dirname, isAbsolute, relative, resolve }] = await Promise.all([
+        const [{ spawn }, fs, { dirname, isAbsolute, join, relative, resolve }] = await Promise.all([
             import('node:child_process'),
             import('node:fs/promises'),
             import('node:path'),
@@ -23,10 +25,36 @@ export function processSandbox(options) {
                 throw new SandboxPathError(file);
             return resolved;
         };
-        return { spawn, fs, dirname, root, inside };
+        return { spawn, fs, dirname, join, relative, root, inside };
     })();
     ready.catch(() => undefined);
     const maxOutput = options.maxOutputBytes ?? 1_048_576;
+    const walk = async (directory) => {
+        const { fs, join, relative, root, inside } = await ready;
+        const start = inside(directory);
+        const slash = (path) => path.replace(/\\/g, '/');
+        const files = [];
+        const queue = [start];
+        let walked = 0;
+        while (queue.length > 0 && walked < WALK_LIMIT) {
+            const current = queue.shift();
+            const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+            for (const entry of entries) {
+                walked += 1;
+                if (walked > WALK_LIMIT)
+                    break;
+                const full = join(current, entry.name);
+                if (entry.isDirectory()) {
+                    if (!SKIPPED_DIRECTORIES.has(entry.name))
+                        queue.push(full);
+                }
+                else if (entry.isFile()) {
+                    files.push({ full, fromRoot: slash(relative(root, full)), fromStart: slash(relative(start, full)) });
+                }
+            }
+        }
+        return files.sort((a, b) => (a.fromRoot < b.fromRoot ? -1 : a.fromRoot > b.fromRoot ? 1 : 0));
+    };
     return {
         name: 'process (development only)',
         isolation: { filesystem: false, network: false, processes: false },
@@ -108,6 +136,40 @@ export function processSandbox(options) {
                 throw new SandboxPathError(file);
             await fs.rm(target, { recursive: true, force: true });
         },
+        async glob(pattern, globOptions = {}) {
+            const matches = globMatcher(pattern);
+            return (await walk(globOptions.cwd ?? '.'))
+                .filter((file) => matches(file.fromStart))
+                .slice(0, globOptions.limit ?? 1_000)
+                .map((file) => file.fromRoot);
+        },
+        async grep(pattern, grepOptions = {}) {
+            const { fs } = await ready;
+            const expression = new RegExp(pattern, grepOptions.ignoreCase ? 'i' : '');
+            const only = grepOptions.glob ? globMatcher(grepOptions.glob) : undefined;
+            const limit = grepOptions.limit ?? 200;
+            const found = [];
+            let scanned = 0;
+            for (const file of await walk(grepOptions.cwd ?? '.')) {
+                if (only && !only(file.fromStart))
+                    continue;
+                const size = (await fs.stat(file.full).catch(() => undefined))?.size;
+                if (size === undefined || size > GREP_FILE_BYTES)
+                    continue;
+                scanned += size;
+                if (scanned > GREP_TOTAL_BYTES)
+                    break;
+                const lines = matchingLines(await fs.readFile(file.full), expression, limit - found.length);
+                found.push(...lines.map((match) => ({ file: file.fromRoot, ...match })));
+                if (found.length >= limit)
+                    break;
+            }
+            return found;
+        },
+        async readBytes(file) {
+            const { fs, inside } = await ready;
+            return fs.readFile(inside(file));
+        },
     };
 }
 function killTree(spawn, pid) {
@@ -182,9 +244,100 @@ export function sandboxTools(sandbox, options = {}) {
                 execute: async (args) => list(local(args.path)),
             });
         }
+        if (sandbox.glob) {
+            const glob = sandbox.glob.bind(sandbox);
+            tools.push({
+                name: 'glob_files',
+                description: `Finds files by a glob, such as **/*.ts or src/*.{js,json}, and lists their paths relative to ${mount}, at most ${GLOB_LIMIT}.`,
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        pattern: { type: 'string', description: 'The glob the paths must match' },
+                        path: { type: 'string', description: 'The directory to search. Defaults to the whole workspace' },
+                    },
+                    required: ['pattern'],
+                },
+                capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+                execute: async (args) => {
+                    const files = await glob(String(args.pattern ?? '**'), { cwd: local(args.path), limit: GLOB_LIMIT + 1 });
+                    if (files.length === 0)
+                        return 'No files match.';
+                    const shown = files.slice(0, GLOB_LIMIT).join('\n');
+                    return files.length > GLOB_LIMIT ? `${shown}\n[more files match: narrow the glob]` : shown;
+                },
+            });
+        }
+        if (sandbox.grep) {
+            const grep = sandbox.grep.bind(sandbox);
+            tools.push({
+                name: 'grep_files',
+                description: `Searches files for lines matching a regular expression and lists each as path:line: text, at most ${GREP_LIMIT}. Large and binary files are skipped.`,
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        pattern: { type: 'string', description: 'The regular expression to find' },
+                        path: { type: 'string', description: 'The directory to search. Defaults to the whole workspace' },
+                        glob: { type: 'string', description: 'Searches only files matching this glob, such as **/*.ts' },
+                        ignore_case: { type: 'boolean', description: 'Matches without regard to case' },
+                    },
+                    required: ['pattern'],
+                },
+                capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+                execute: async (args) => {
+                    const found = await grep(String(args.pattern ?? ''), {
+                        cwd: local(args.path),
+                        ...(typeof args.glob === 'string' && args.glob ? { glob: args.glob } : {}),
+                        ignoreCase: args.ignore_case === true,
+                        limit: GREP_LIMIT + 1,
+                    });
+                    if (found.length === 0)
+                        return 'No lines match.';
+                    const shown = found
+                        .slice(0, GREP_LIMIT)
+                        .map((match) => `${match.file}:${match.line}: ${match.text}`)
+                        .join('\n');
+                    return found.length > GREP_LIMIT ? `${shown}\n[more lines match: narrow the search]` : shown;
+                },
+            });
+        }
+        if (sandbox.readBytes) {
+            const readBytes = sandbox.readBytes.bind(sandbox);
+            const maxBytes = options.maxMediaBytes ?? 10 * 1_048_576;
+            tools.push({
+                name: 'read_media',
+                description: `Shows you an image (PNG, JPEG, GIF, WebP), audio (WAV, MP3, FLAC, OGG, AAC), or a PDF in the sandbox as content you see or hear, not as text. Paths are relative to ${mount}.`,
+                parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+                capabilities: (args) => [`filesystem:read:${mounted(args.path)}`],
+                execute: async (args) => {
+                    const file = local(args.path);
+                    const mimeType = MEDIA_TYPES[file.split('.').pop()?.toLowerCase() ?? ''];
+                    if (!mimeType)
+                        throw new Error(`${file} is not an image, audio, or PDF file; read text with read_file`);
+                    const bytes = await readBytes(file);
+                    if (bytes.byteLength > maxBytes) {
+                        throw new Error(`${file} is ${bytes.byteLength} bytes, over the ${maxBytes}-byte limit for media`);
+                    }
+                    return mediaOutput(file, mimeType, bytes);
+                },
+            });
+        }
     }
     return tools;
 }
+const GLOB_LIMIT = 500;
+const GREP_LIMIT = 200;
+function mediaOutput(file, mimeType, bytes) {
+    const data = encodeBase64(bytes);
+    const part = mimeType.startsWith('image/')
+        ? { type: 'image', source: { base64: data, mimeType } }
+        : mimeType.startsWith('audio/')
+            ? { type: 'audio', source: { base64: data, format: mimeType.slice('audio/'.length) } }
+            : { type: 'document', source: { base64: data, mimeType }, filename: file.split('/').pop() ?? file };
+    return {
+        type: 'tool_output',
+        content: [{ type: 'text', text: `${file} (${mimeType}, ${bytes.byteLength} bytes)` }, part],
+    };
+}
 export async function runSandboxConformance(create, options = {}) {
     const node = options.node ?? 'node';
     const js = (code) => `${node} -e "${code}"`;

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

@@ -0,0 +1,39 @@
+/**
+ * Tool search: an agent with hundreds of tools marks most of them `deferred`, and the model finds the
+ * few a task needs with `search_tools` instead of reading every definition on every call.
+ *
+ * The search ranks tools by BM25 over their names, descriptions, and argument names and descriptions,
+ * and answers with the tools it found as `tool_reference` parts. A provider with tool references,
+ * such as Anthropic, expands each reference into the tool's definition where it stands, so the tool
+ * list at the front of the prompt never changes; every other provider is sent a found tool from then
+ * on. Either way the model calls a found tool on its next turn.
+ */
+import type { ToolDefinition } from '../types/messages.js';
+/** The name of the search tool an agent with deferred tools offers. */
+export declare const TOOL_SEARCH_NAME = "search_tools";
+/** Options for `toolSearchTool()`. */
+export interface ToolSearchOptions {
+    /** How many tools a search returns unless the model asks for another number. Defaults to 5. */
+    limit?: number;
+    /** The most a model may ask for. Defaults to 20. */
+    maxLimit?: number;
+}
+/** One tool a search found, with its score. */
+export interface ToolSearchHit {
+    /** The tool. */
+    tool: ToolDefinition;
+    /** Its BM25 score for the query; higher is closer. */
+    score: number;
+}
+/**
+ * Ranks tools against a query by BM25 over their names, descriptions, and arguments. A tool's name
+ * counts twice, so a query that names a tool finds it first. Returns the tools that match at all,
+ * best first, at most `limit`.
+ */
+export declare function searchTools(tools: readonly ToolDefinition[], query: string, limit?: number): ToolSearchHit[];
+/**
+ * The tool an agent offers when it has deferred tools: `search_tools`, which finds deferred tools by
+ * what a task needs and answers with them as tool references. `createAgent()` adds it on its own; an
+ * application's own loop can offer it the same way.
+ */
+export declare function toolSearchTool(tools: readonly ToolDefinition[], options?: ToolSearchOptions): ToolDefinition;