nexus-ai-pro 2.5.0 → 2.7.0

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

@@ -1,15 +1,32 @@
 import type { ContentPart, Message, ToolContext, ToolDefinition, ToolOutput } from '../types/messages.js';
 import type { ToolExecutionResult } from '../types/agent.js';
-/** Defines a tool the model can call, typing its arguments. */
+/** How a tool built with `tool()` runs: once, with `execute`, or reporting progress, with `stream`. */
+export type ToolBody<TArgs> = {
+    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
+    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
+    stream?: never;
+} | {
+    /**
+     * Runs the tool, yielding progress while it works and returning the result. See
+     * `ToolDefinition.stream`.
+     */
+    stream: (args: TArgs, context: ToolContext) => AsyncGenerator<unknown, unknown, undefined>;
+    execute?: never;
+};
+/**
+ * Defines a tool the model can call, typing its arguments. A tool given `stream` gets an `execute`
+ * too, which runs the stream and reports each yield to `context.progress`, so it works wherever a
+ * tool is executed.
+ */
 export declare function tool<TArgs extends Record<string, unknown> = Record<string, unknown>>(definition: {
     name: string;
     description: string;
     parameters: Record<string, unknown>;
-    /** Runs the tool. In an agent, `context` says who the run is for and carries its signal and store. */
-    execute: (args: TArgs, context: ToolContext) => Promise<unknown> | unknown;
     /** What the tool does to the world, for a permission policy; see `ToolDefinition.capabilities`. */
     capabilities?: readonly string[] | ((args: TArgs) => readonly string[]);
-}): ToolDefinition;
+    /** 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
  * a text part. Returned from `execute`, it is sent as the tool message itself, so an image a tool

package/dist/agent/tool.js

@@ -1,10 +1,20 @@
 export function tool(definition) {
     const capabilities = definition.capabilities;
+    const stream = definition.stream;
+    const execute = definition.execute;
     return {
         name: definition.name,
         description: definition.description,
         parameters: definition.parameters,
-        execute: async (args, context) => definition.execute(args, context ?? {}),
+        ...(definition.deferred ? { deferred: true } : {}),
+        ...(stream
+            ? {
+                stream: (args, context) => stream(args, context ?? {}),
+                execute: async (args, context) => drain(stream(args, context ?? {}), context?.progress),
+            }
+            : {
+                execute: async (args, context) => execute(args, context ?? {}),
+            }),
         ...(capabilities === undefined
             ? {}
             : {
@@ -31,6 +41,18 @@ export function toolMessageContent(result) {
         return result.result.content;
     return JSON.stringify(result.ok ? (result.result ?? null) : { error: result.error });
 }
+async function drain(generator, progress) {
+    for (;;) {
+        const step = await generator.next();
+        if (step.done)
+            return step.value;
+        try {
+            progress?.(step.value);
+        }
+        catch {
+        }
+    }
+}
 export class ToolExecutor {
     tools = new Map();
     constructor(tools = []) {
@@ -56,11 +78,13 @@ export class ToolExecutor {
         if (!toolDefinition) {
             return { ok: false, error: `Tool "${name}" is not registered` };
         }
-        if (!toolDefinition.execute) {
-            return { ok: false, error: `Tool "${name}" does not have an execute function` };
+        if (!toolDefinition.execute && !toolDefinition.stream) {
+            return { ok: false, error: `Tool "${name}" does not have an execute or stream function` };
         }
         try {
-            const result = await toolDefinition.execute(args, context);
+            const result = toolDefinition.stream
+                ? await drain(toolDefinition.stream(args, context), context?.progress)
+                : await toolDefinition.execute(args, context);
             return { ok: true, result };
         }
         catch (err) {

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[];

package/dist/deep-agent/helpers.js

@@ -0,0 +1,235 @@
+import { agentInput, createAgent, } from '../agent/create-agent.js';
+const MARK = 'deepAgentHelper';
+export function helperTools(setup) {
+    const declared = new Map(setup.declared.map((helper) => [helper.name, helper]));
+    const created = new Map();
+    const graphs = new Map();
+    const live = new Map();
+    const spec = (name, instructions, thread) => {
+        const helper = declared.get(name);
+        if (helper) {
+            return {
+                name,
+                instructions: helper.instructions,
+                ...(helper.tools ? { tools: helper.tools } : {}),
+                ...(helper.model ? { model: helper.model } : {}),
+                maxIterations: helper.maxIterations ?? 20,
+                created: false,
+            };
+        }
+        const mine = created.get(thread) ?? new Map();
+        const existing = mine.get(name);
+        if (existing)
+            return existing;
+        const known = [...declared.keys(), ...mine.keys()].join(', ') || 'none';
+        if (!setup.create)
+            throw new Error(`No helper named "${name}"; the helpers are ${known}`);
+        if (!/^[A-Za-z][\w-]{0,39}$/.test(name)) {
+            throw new Error('A new helper needs a name of letters, digits, _ and -, starting with a letter');
+        }
+        if (!instructions?.trim())
+            throw new Error(`To create the helper "${name}", give its instructions`);
+        const max = setup.create.max ?? 5;
+        if (mine.size >= max)
+            throw new Error(`This thread has created its ${max} helpers; delegate to one of: ${known}`);
+        const made = {
+            name,
+            instructions: instructions.trim(),
+            ...(setup.create.tools ? { tools: setup.create.tools } : {}),
+            ...(setup.create.model ? { model: setup.create.model } : {}),
+            maxIterations: setup.create.maxIterations ?? 10,
+            created: true,
+        };
+        mine.set(name, made);
+        created.set(thread, mine);
+        return made;
+    };
+    const graph = (helper, durable) => {
+        const key = JSON.stringify([helper.name, helper.created ? helper.instructions : '', durable]);
+        const cached = graphs.get(key);
+        if (cached)
+            return cached;
+        const allowed = helper.tools ? new Set(helper.tools) : undefined;
+        const made = createAgent({
+            ...setup.agentOptions,
+            name: `${setup.name}.${helper.name}`,
+            ...(helper.model ? { model: helper.model } : {}),
+            maxIterations: helper.maxIterations,
+            systemPrompt: `${helper.instructions}\n\n${setup.note}`,
+            tools: setup.tools.filter((candidate) => (allowed ? allowed.has(candidate.name) : true)),
+            ...(setup.permissions ? { permissions: setup.permissions } : {}),
+            checkpointer: durable && setup.checkpointer ? setup.checkpointer : false,
+        });
+        graphs.set(key, made);
+        return made;
+    };
+    const runOptions = (context, namespace, extra = {}) => {
+        const forward = context.forward;
+        const onEvent = extra.onEvent;
+        return {
+            ...extra,
+            ...(context.principal ? { principal: context.principal } : {}),
+            ...(forward || onEvent
+                ? {
+                    subgraphEvents: Boolean(forward),
+                    onEvent: (event) => {
+                        onEvent?.(event);
+                        forward?.(event, [namespace]);
+                    },
+                }
+                : {}),
+        };
+    };
+    const outcome = (helper, ended) => {
+        if (ended?.status === 'completed') {
+            return {
+                helper,
+                ok: true,
+                answer: ended.state.answer || `The ${helper} helper finished without an answer (${ended.state.stopReason}).`,
+            };
+        }
+        const why = ended?.error ? (ended.error.message ?? String(ended.error)) : ended?.status;
+        return { helper, ok: false, error: `The ${helper} helper stopped: ${why ?? 'it did not run'}` };
+    };
+    const thread = (parent, task) => `${parent ?? 'thread'}/helper/${task}`;
+    const start = async (helper, task, threadId, context) => {
+        if (live.has(threadId))
+            return;
+        const runner = graph(helper, true);
+        const stored = setup.checkpointer ? await runner.state(threadId) : undefined;
+        let ready = () => { };
+        const started = new Promise((resolve) => {
+            ready = resolve;
+        });
+        const options = runOptions(context, threadId.slice(threadId.lastIndexOf('/') + 1), {
+            threadId,
+            metadata: {
+                [MARK]: {
+                    name: helper.name,
+                    created: helper.created,
+                    ...(helper.created ? { instructions: helper.instructions } : {}),
+                },
+            },
+            onEvent: (event) => {
+                if (event.type === 'checkpoint')
+                    ready();
+            },
+        });
+        const steps = stored === undefined
+            ? runner.stream(agentInput(task ?? ''), options)
+            : stored.status === 'completed' || stored.status === 'failed'
+                ? undefined
+                : runner.continue(threadId, options);
+        const drive = async () => {
+            let last;
+            if (steps)
+                for await (const step of steps)
+                    last = step;
+            return outcome(helper.name, (setup.checkpointer ? await runner.state(threadId) : undefined) ?? last ?? stored);
+        };
+        const entry = { helper: helper.name, settled: false, outcome: Promise.resolve(undefined) };
+        entry.outcome = drive()
+            .catch((error) => ({
+            helper: helper.name,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        }))
+            .finally(() => {
+            entry.settled = true;
+            ready();
+        });
+        live.set(threadId, entry);
+        await started;
+    };
+    const names = [...declared.keys()];
+    const delegate = {
+        name: 'delegate',
+        description: [
+            'Hands a self-contained task to a helper, which works in a fresh context and returns its answer.',
+            'With background, the helper works while you go on: you get a task id at once, and collect_helper returns its answer.',
+            ...(setup.create ? ['To create a helper for a task no helper fits, give a new name and its instructions.'] : []),
+        ].join(' '),
+        parameters: {
+            type: 'object',
+            properties: {
+                agent: setup.create
+                    ? { type: 'string', description: `A helper (${names.join(', ') || 'none yet'}), or a new name to create one` }
+                    : { type: 'string', enum: names },
+                task: { type: 'string', description: 'Everything the helper needs to know: it sees nothing else.' },
+                ...(setup.create
+                    ? { instructions: { type: 'string', description: 'For a new helper: who it is and how it works.' } }
+                    : {}),
+                background: { type: 'boolean', description: 'Runs the helper while you go on.' },
+            },
+            required: ['agent', 'task'],
+        },
+        capabilities: [],
+        execute: async (args, context = {}) => {
+            const helper = spec(String(args.agent ?? ''), typeof args.instructions === 'string' ? args.instructions : undefined, context.threadId ?? '');
+            const task = String(args.task ?? '');
+            const call = context.toolCallId ?? Math.random().toString(36).slice(2, 10);
+            if (args.background !== true) {
+                const result = await graph(helper, false).invoke(agentInput(task), runOptions(context, `${helper.name}@${call}`, context.signal ? { signal: context.signal } : {}));
+                return (result.state.answer || `The ${helper.name} helper finished without an answer (${result.state.stopReason}).`);
+            }
+            const running = [...live.entries()].filter(([id, entry]) => id.startsWith(thread(context.threadId, '')) && !entry.settled).length;
+            if (running >= setup.maxBackground) {
+                throw new Error(`${running} helpers are already working in the background; collect one with collect_helper first`);
+            }
+            const id = `${helper.name}@${call}`;
+            await start(helper, task, thread(context.threadId, id), context);
+            return `The ${helper.name} helper is working in the background as task ${id}. Collect its answer with collect_helper.`;
+        },
+    };
+    const collect = {
+        name: 'collect_helper',
+        description: 'Returns the answer of a helper working in the background, by its task id, waiting up to wait_seconds for it. Without a task, lists the tasks of this run.',
+        parameters: {
+            type: 'object',
+            properties: {
+                task: { type: 'string', description: 'The task id delegate returned' },
+                wait_seconds: { type: 'number', description: 'How long to wait for the answer, up to 120. Defaults to 0.' },
+            },
+        },
+        capabilities: [],
+        execute: async (args, context = {}) => {
+            const prefix = thread(context.threadId, '');
+            if (typeof args.task !== 'string' || !args.task) {
+                const tasks = [...live.entries()].filter(([id]) => id.startsWith(prefix));
+                if (tasks.length === 0)
+                    return 'No helper is working in the background in this process.';
+                return tasks
+                    .map(([id, entry]) => `${id.slice(prefix.length)}: ${entry.settled ? 'finished' : 'working'}`)
+                    .join('\n');
+            }
+            const task = args.task;
+            const threadId = thread(context.threadId, task);
+            if (!live.has(threadId)) {
+                const stored = setup.checkpointer ? await setup.checkpointer.get(threadId) : undefined;
+                if (!stored)
+                    throw new Error(`No helper task "${task}" in this run`);
+                const mark = stored.metadata?.[MARK];
+                const name = mark?.name ?? task.slice(0, task.lastIndexOf('@'));
+                const helper = mark?.created
+                    ? spec(name, mark.instructions, context.threadId ?? '')
+                    : spec(name, undefined, context.threadId ?? '');
+                await start(helper, undefined, threadId, context);
+            }
+            const entry = live.get(threadId);
+            const waitMs = Math.min(Math.max(Number(args.wait_seconds) || 0, 0), 120) * 1_000;
+            let timer;
+            const ended = await Promise.race([
+                entry.outcome,
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(undefined), waitMs);
+                }),
+            ]).finally(() => clearTimeout(timer));
+            if (!ended)
+                return `The ${entry.helper} helper is still working on task ${task}. Collect it again later.`;
+            if (!ended.ok)
+                throw new Error(ended.error);
+            return `The ${ended.helper} helper's answer: ${ended.answer}`;
+        },
+    };
+    return [delegate, collect];
+}

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

@@ -7,11 +7,14 @@
  * support as any agent.
  */
 import { type AgentGraph, type AgentMiddleware, type CreateAgentOptions } from '../agent/create-agent.js';
+import { type Interpreter } from '../agent/interpreter.js';
 import { type ContextEditorOptions } from '../agent/middleware/context-editor.js';
 import { type ContextOffloadOptions } from '../agent/middleware/filesystem.js';
 import { type ToolSelectorOptions } from '../agent/middleware/tool-selector.js';
 import { type PermissionPolicyLike } from '../agent/permissions.js';
 import { type Sandbox } from '../agent/sandbox.js';
+import { type DeepHelperLimits } from './helpers.js';
+export type { DeepHelperLimits } from './helpers.js';
 /** A helper the deep agent can hand a self-contained piece of work to, with a fresh context. */
 export interface DeepSubagent {
     /** Its name, as the agent delegates to it. */
@@ -58,8 +61,24 @@ export interface DeepAgentOptions extends Omit<CreateAgentOptions, 'systemPrompt
     commands?: readonly string[];
     /** Records a plan with `write_todos` and keeps it current. Defaults to true. */
     planning?: boolean;
-    /** Helpers the agent can delegate to through one `delegate` tool. */
+    /**
+     * Runs the model's code with the agent's own tools callable from it, as `run_code`, so many calls
+     * take one step. Every call the code makes is decided by the agent's policy, and a tool that needs
+     * approval cannot be called from code. Given one, the default policy grants `code`.
+     */
+    interpreter?: Interpreter;
+    /**
+     * Helpers the agent can delegate to through one `delegate` tool. The agent waits for a helper's
+     * answer, or sets `background` and collects it later with `collect_helper`.
+     */
     subagents?: readonly DeepSubagent[];
+    /**
+     * Lets the agent create helpers during a run, from instructions it writes, within these limits.
+     * Off unless given.
+     */
+    createHelpers?: DeepHelperLimits;
+    /** How many helpers may work in the background in one thread at once. Defaults to 4. */
+    maxBackgroundHelpers?: number;
     /** Skills the agent can load through `load_skill`. */
     skills?: readonly DeepSkill[];
     /** Instruction files from the sandbox the model sees on every call. Defaults to `AGENTS.md`. */