nexus-ai-pro 2.6.0 → 2.7.0

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;

package/dist/agent/tool-search.js

@@ -0,0 +1,113 @@
+export const TOOL_SEARCH_NAME = 'search_tools';
+export function searchTools(tools, query, limit = 5) {
+    return indexTools(tools)(query, limit);
+}
+export function toolSearchTool(tools, options = {}) {
+    const search = indexTools(tools);
+    const fallback = Math.max(1, options.limit ?? 5);
+    const most = Math.max(fallback, options.maxLimit ?? 20);
+    return {
+        name: TOOL_SEARCH_NAME,
+        description: `Finds tools for a task among ${tools.length} more tools that are not loaded yet, by their names, descriptions, and arguments. Describe what you need to do, such as "create a calendar event"; the tools found can be called right after.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'What the tool should do, in a few words' },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: most,
+                    description: `How many tools to return. Defaults to ${fallback}`,
+                },
+            },
+            required: ['query'],
+        },
+        capabilities: [],
+        execute: async (args) => {
+            const query = String(args.query ?? '');
+            const wanted = Math.min(most, Math.max(1, Math.floor(Number(args.limit) || fallback)));
+            const hits = search(query, wanted);
+            if (hits.length === 0) {
+                return {
+                    type: 'tool_output',
+                    content: [{ type: 'text', text: `No tool matches "${query}". Try other words.` }],
+                };
+            }
+            const listed = hits.map(({ tool }) => `- ${tool.name}: ${short(tool.description)}`).join('\n');
+            const references = hits.map(({ tool }) => ({ type: 'tool_reference', name: tool.name }));
+            return {
+                type: 'tool_output',
+                content: [{ type: 'text', text: `Found ${hits.length}, which you can call now:\n${listed}` }, ...references],
+            };
+        },
+    };
+}
+const short = (text) => (text.length > 200 ? `${text.slice(0, 197)}...` : text);
+function words(text) {
+    return (text
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .toLowerCase()
+        .match(/[a-z0-9]+/g) ?? [])
+        .filter((word) => word.length > 1 && !STOP.has(word))
+        .map((word) => (word.length > 3 ? word.replace(/(?:ies|es|s)$/, (end) => (end === 'ies' ? 'y' : '')) : word));
+}
+const STOP = new Set([
+    'the',
+    'an',
+    'and',
+    'or',
+    'of',
+    'to',
+    'in',
+    'on',
+    'for',
+    'it',
+    'is',
+    'as',
+    'by',
+    'with',
+    'use',
+    'this',
+]);
+function documentOf(tool) {
+    const properties = tool.parameters.properties ?? {};
+    const argumentText = Object.entries(properties)
+        .map(([name, schema]) => `${name} ${typeof schema?.description === 'string' ? schema.description : ''}`)
+        .join(' ');
+    const name = words(tool.name);
+    return [...name, ...name, ...words(tool.description), ...words(argumentText)];
+}
+function indexTools(tools) {
+    const documents = tools.map((tool) => {
+        const counts = new Map();
+        const terms = documentOf(tool);
+        for (const term of terms)
+            counts.set(term, (counts.get(term) ?? 0) + 1);
+        return { tool, counts, length: terms.length };
+    });
+    const average = documents.reduce((sum, document) => sum + document.length, 0) / Math.max(1, documents.length);
+    const frequency = new Map();
+    for (const document of documents)
+        for (const term of document.counts.keys())
+            frequency.set(term, (frequency.get(term) ?? 0) + 1);
+    const k1 = 1.2;
+    const b = 0.75;
+    return (query, limit) => {
+        const terms = [...new Set(words(query))];
+        const hits = [];
+        for (const document of documents) {
+            let score = 0;
+            for (const term of terms) {
+                const count = document.counts.get(term);
+                if (!count)
+                    continue;
+                const appears = frequency.get(term) ?? 0;
+                const idf = Math.log(1 + (documents.length - appears + 0.5) / (appears + 0.5));
+                score += (idf * count * (k1 + 1)) / (count + k1 * (1 - b + (b * document.length) / average));
+            }
+            if (score > 0)
+                hits.push({ tool: document.tool, score });
+        }
+        return hits.sort((x, y) => y.score - x.score || x.tool.name.localeCompare(y.tool.name)).slice(0, limit);
+    };
+}

package/dist/agent/tool.d.ts

@@ -24,6 +24,8 @@ export declare function tool<TArgs extends Record<string, unknown> = Record<stri
     parameters: Record<string, unknown>;
     /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
     capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
+    /** Loads the tool only once the model finds it; see `ToolDefinition.deferred`. */
+    deferred?: boolean;
 } & ToolBody<TArgs>): ToolDefinition;
 /**
  * Builds a tool's result as content: text, images, and asset references, in order. A string becomes

package/dist/agent/tool.js

@@ -6,6 +6,7 @@ export function tool(definition) {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
+        ...(definition.deferred ? { deferred: true } : {}),
         ...(stream
             ? {
                 stream: (args, context) => stream(args, context ?? {}),

package/dist/context/window.js

@@ -275,6 +275,10 @@ export class ContextWindowManager {
             return 'transcript' in part.source ? part.source.transcript : '[audio content]';
         if (part.type === 'video')
             return '[video content]';
+        if (part.type === 'document')
+            return '[document content]';
+        if (part.type === 'tool_reference')
+            return `[tool ${part.name}]`;
         if (part.type === 'asset')
             return `[asset ${part.asset.mimeType}]`;
         return '[content]';

package/dist/deep-agent/helpers.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Helpers beside a deep agent: helpers it delegates to and waits for, helpers that run in the
+ * background while it goes on, and helpers it creates during a run from instructions it writes.
+ *
+ * A background helper runs on a thread of its own, named after the call that started it, and writes
+ * its checkpoints to the deep agent's checkpointer. A crash leaves the helper's finished steps behind
+ * it: collecting the task in a new process carries the helper on from its last checkpoint, and a call
+ * the agent repeats after the crash finds the same thread instead of starting the helper again.
+ */
+import { type CreateAgentOptions } from '../agent/create-agent.js';
+import type { PermissionPolicyLike } from '../agent/permissions.js';
+import type { GraphCheckpointer } from '../types/graph.js';
+import type { ToolDefinition } from '../types/messages.js';
+/** Limits on the helpers a deep agent creates during a run, from instructions it writes. */
+export interface DeepHelperLimits {
+    /**
+     * The tools a created helper may use, by name, from the agent's own. Defaults to all of them. A tool
+     * that needs approval is never a helper's.
+     */
+    tools?: readonly string[];
+    /** The model a created helper runs on. Defaults to the agent's. */
+    model?: string;
+    /** Model calls a created helper may make. Defaults to 10. */
+    maxIterations?: number;
+    /** How many helpers the agent may create in one thread. Defaults to 5. */
+    max?: number;
+}
+/** What the deep agent hands the helper tools. */
+export interface HelperSetup {
+    /** The helpers the application declared. */
+    declared: ReadonlyArray<{
+        name: string;
+        description: string;
+        instructions: string;
+        tools?: readonly string[];
+        model?: string;
+        maxIterations?: number;
+    }>;
+    /** Limits on created helpers, when the agent may create them. */
+    create?: DeepHelperLimits;
+    /** The tools a helper may be given: the agent's own, less any that need approval. */
+    tools: readonly ToolDefinition[];
+    /** `createAgent()` options every helper shares. */
+    agentOptions: Omit<CreateAgentOptions, 'interruptOn' | 'tools' | 'systemPrompt' | 'permissions' | 'checkpointer'>;
+    /** The policy every helper runs under. */
+    permissions?: PermissionPolicyLike;
+    /** Where background helpers keep their checkpoints. */
+    checkpointer?: GraphCheckpointer;
+    /** The deep agent's name, for the helpers' names. */
+    name: string;
+    /** Appended to every helper's instructions. */
+    note: string;
+    /** How many helpers may run in the background in one thread at once. */
+    maxBackground: number;
+}
+/** `delegate` and `collect_helper`, sharing the helpers they run. */
+export declare function helperTools(setup: HelperSetup): ToolDefinition[];