nexus-ai-pro 2.6.0 → 2.7.0

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`. */

package/dist/deep-agent/index.js

@@ -1,49 +1,68 @@
-import { agentInput, createAgent, } from '../agent/create-agent.js';
+import { createAgent } from '../agent/create-agent.js';
+import { codeTool } from '../agent/interpreter.js';
 import { contextEditor } from '../agent/middleware/context-editor.js';
 import { filesystemContext } from '../agent/middleware/filesystem.js';
 import { toolSelector } from '../agent/middleware/tool-selector.js';
 import { permissionPolicy } from '../agent/permissions.js';
 import { sandboxTools } from '../agent/sandbox.js';
 import { tool } from '../agent/tool.js';
+import { helperTools } from './helpers.js';
 const MOUNT = '/workspace';
 const CORE_TOOLS = [
     'write_todos',
     'delegate',
+    'collect_helper',
     'load_skill',
     'read_file',
     'write_file',
     'edit_file',
     'list_files',
+    'glob_files',
+    'grep_files',
+    'read_media',
     'run_command',
+    'run_code',
+    'search_tools',
 ];
 export function createDeepAgent(options) {
-    const { instructions, sandbox, commands = [], planning = true, subagents = [], skills = [], include = ['AGENTS.md'], offload, contextEditing, toolSelection, permissions, middleware = [], tools: extraTools = [], ...agentOptions } = options;
+    const { instructions, sandbox, commands = [], planning = true, interpreter, subagents = [], createHelpers, maxBackgroundHelpers = 4, skills = [], include = ['AGENTS.md'], offload, contextEditing, toolSelection, permissions, middleware = [], tools: extraTools = [], ...agentOptions } = options;
     const workspace = sandbox
         ? [...sandboxTools(sandbox, { shell: commands.length > 0, mount: MOUNT }), editFileTool(sandbox)]
         : [];
-    const own = [
+    const approved = new Set(Object.keys(agentOptions.interruptOn ?? {}));
+    const policy = permissions === false ? undefined : (permissions ?? defaultPolicy(commands, Boolean(interpreter)));
+    const direct = [
         ...(planning ? [writeTodosTool()] : []),
         ...(skills.length > 0 ? [loadSkillTool(skills, sandbox)] : []),
         ...workspace,
         ...extraTools,
     ];
-    const helpers = new Map();
-    const approved = new Set(Object.keys(agentOptions.interruptOn ?? {}));
-    const { interruptOn: _approvals, ...helperOptions } = agentOptions;
-    for (const helper of subagents) {
-        const allowed = helper.tools ? new Set(helper.tools) : undefined;
-        helpers.set(helper.name, createAgent({
-            ...helperOptions,
-            name: `${options.name ?? 'deep-agent'}.${helper.name}`,
-            ...(helper.model ? { model: helper.model } : {}),
-            maxIterations: helper.maxIterations ?? 20,
-            systemPrompt: `${helper.instructions}\n\n${WORKSPACE_NOTE}`,
-            tools: own.filter((candidate) => !approved.has(candidate.name) && (allowed ? allowed.has(candidate.name) : true)),
-            ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
-            checkpointer: false,
-        }));
-    }
-    const tools = [...own, ...(helpers.size > 0 ? [delegateTool(subagents, helpers)] : [])];
+    const own = [
+        ...direct,
+        ...(interpreter
+            ? [
+                codeTool(interpreter, {
+                    tools: direct.filter((candidate) => !approved.has(candidate.name)),
+                    ...(policy ? { permissions: policy } : {}),
+                }),
+            ]
+            : []),
+    ];
+    const { interruptOn: _approvals, checkpointer, ...helperOptions } = agentOptions;
+    const helping = subagents.length > 0 || createHelpers
+        ? helperTools({
+            declared: subagents,
+            ...(createHelpers ? { create: createHelpers } : {}),
+            tools: own.filter((candidate) => !approved.has(candidate.name)),
+            agentOptions: helperOptions,
+            ...(policy ? { permissions: policy } : {}),
+            ...(checkpointer ? { checkpointer } : {}),
+            name: options.name ?? 'deep-agent',
+            note: WORKSPACE_NOTE,
+            maxBackground: maxBackgroundHelpers,
+        })
+        : [];
+    const tools = [...own, ...helping];
     const kit = [
         ...(sandbox && (include.length > 0 || offload !== false)
             ? [
@@ -70,17 +89,28 @@ export function createDeepAgent(options) {
     return createAgent({
         maxIterations: 40,
         ...agentOptions,
-        systemPrompt: systemPrompt(instructions, { planning, sandbox: Boolean(sandbox), commands, subagents, skills }),
+        systemPrompt: systemPrompt(instructions, {
+            planning,
+            sandbox: Boolean(sandbox),
+            search: Boolean(sandbox?.glob && sandbox.grep),
+            media: Boolean(sandbox?.readBytes),
+            code: interpreter?.language,
+            commands,
+            subagents,
+            create: Boolean(createHelpers),
+            skills,
+        }),
         tools,
         middleware: [...kit, ...middleware],
-        ...(permissions === false ? {} : { permissions: permissions ?? defaultPolicy(commands) }),
+        ...(policy ? { permissions: policy } : {}),
     });
 }
-function defaultPolicy(commands) {
+function defaultPolicy(commands, code) {
     return permissionPolicy({
         filesystem: { write: [`${MOUNT}/**`] },
         shell: { allow: commands },
-        tools: { write_todos: 'allow', delegate: 'allow', load_skill: 'allow' },
+        tools: { write_todos: 'allow', delegate: 'allow', collect_helper: 'allow', load_skill: 'allow' },
+        ...(code ? { code: 'allow' } : {}),
     });
 }
 const WORKSPACE_NOTE = `Files live in ${MOUNT}; paths are relative to it.`;
@@ -94,13 +124,26 @@ function systemPrompt(instructions, parts) {
     }
     if (parts.sandbox) {
         lines.push(`${WORKSPACE_NOTE} Read before you change a file; prefer edit_file to rewriting a whole file. A large result may be saved to a file and shown as a preview: read the file when you need the rest.`);
+        if (parts.search) {
+            lines.push('Find files with glob_files and the lines you need with grep_files before reading whole files.');
+        }
+        if (parts.media)
+            lines.push('Look at images, audio, and PDFs with read_media.');
         if (parts.commands.length > 0)
             lines.push(`You may run these commands: ${parts.commands.join(', ')}.`);
     }
-    if (parts.subagents.length > 0) {
-        lines.push('', 'Delegate a self-contained piece of work with delegate, to one of:');
+    if (parts.code) {
+        lines.push(`When a task takes many tool calls, or a filter on what they return, write ${parts.code} for run_code and call the tools from it in one step.`);
+    }
+    if (parts.subagents.length > 0 || parts.create) {
+        lines.push('', 'Delegate a self-contained piece of work with delegate.');
+        if (parts.subagents.length > 0)
+            lines.push('The helpers:');
         for (const helper of parts.subagents)
             lines.push(`- ${helper.name}: ${helper.description}`);
+        if (parts.create)
+            lines.push('For work none of them fits, create a helper: give delegate a new name and its instructions.');
+        lines.push('Set background to keep working while a helper runs, and collect its answer with collect_helper when you need it.');
     }
     if (parts.skills.length > 0) {
         lines.push('', 'Skills you can load with load_skill when a task calls for one:');
@@ -189,28 +232,3 @@ function loadSkillTool(skills, sandbox) {
         },
     });
 }
-function delegateTool(subagents, helpers) {
-    return tool({
-        name: 'delegate',
-        description: 'Hands a self-contained task to a helper, which works in a fresh context and returns its answer.',
-        parameters: {
-            type: 'object',
-            properties: {
-                agent: { type: 'string', enum: subagents.map((helper) => helper.name) },
-                task: { type: 'string', description: 'Everything the helper needs to know: it sees nothing else.' },
-            },
-            required: ['agent', 'task'],
-        },
-        capabilities: [],
-        execute: async ({ agent, task }, context) => {
-            const helper = helpers.get(String(agent));
-            if (!helper)
-                throw new Error(`No helper named "${String(agent)}"`);
-            const result = await helper.invoke(agentInput(String(task)), {
-                ...(context.principal ? { principal: context.principal } : {}),
-                ...(context.signal ? { signal: context.signal } : {}),
-            });
-            return (result.state.answer || `The ${String(agent)} helper finished without an answer (${result.state.stopReason}).`);
-        },
-    });
-}

package/dist/evaluate/generate.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Datasets that grow: synthetic examples written from documents, each citing the passage it came
+ * from; adversarial examples grown from the guardrails' own attack patterns; and production runs
+ * promoted from the issues insights found.
+ */
+import type { Issue } from '../insights/clusters.js';
+import { type AttackCategory } from '../security/injection-detector.js';
+import type { Dataset, DatasetExample, Evaluator } from '../types/evaluate.js';
+import type { CompletionRequest } from '../types/messages.js';
+import type { NexusResponse } from '../types/response.js';
+import type { Run } from '../types/tracing.js';
+/** A document to write examples from. */
+export interface SyntheticDocument {
+    /** Names the document in every citation. */
+    id: string;
+    /** Its text. */
+    text: string;
+    /** Its title, carried into citations. */
+    title?: string;
+}
+/** One passage of a document, as the writer sees it. */
+export interface SyntheticPassage {
+    /** The document it is from. */
+    document: SyntheticDocument;
+    /** Its position among the document's passages, from 0. */
+    index: number;
+    /** Where it starts in the document, in characters. */
+    start: number;
+    /** Where it ends. */
+    end: number;
+    /** Its text. */
+    text: string;
+}
+/** An example the writer drafts: a question, its answer, and the words of the passage that support it. */
+export interface SyntheticDraft {
+    /** What the target is asked. */
+    question: string;
+    /** The answer the passage supports. */
+    answer: string;
+    /** Words copied from the passage that support the answer. A draft whose quote is not there is dropped. */
+    quote: string;
+}
+/** Where an example came from: the document, the passage, and the supporting words. */
+export interface SyntheticCitation {
+    /** The document's id. */
+    document: string;
+    /** Its title, when it has one. */
+    title?: string;
+    /** The passage's position in the document. */
+    passage: number;
+    /** Where the supporting words start in the document, in characters. */
+    start: number;
+    /** Where they end. */
+    end: number;
+    /** The supporting words, as the document has them. */
+    quote: string;
+}
+/** A model that writes drafts. */
+export interface SyntheticModelClient {
+    /** Runs one completion. */
+    complete(request: CompletionRequest): Promise<NexusResponse>;
+}
+/** Options for `syntheticDataset()`. Give it `generate`, or a `client` and `model`. */
+export interface SyntheticDatasetOptions {
+    /** The dataset's name. */
+    name: string;
+    /** The documents to write examples from. */
+    documents: readonly SyntheticDocument[];
+    /** Writes drafts for one passage. */
+    generate?: (passage: SyntheticPassage, count: number) => Promise<SyntheticDraft[]> | SyntheticDraft[];
+    /** A model that writes drafts with a built-in prompt, when there is no `generate`. */
+    client?: SyntheticModelClient;
+    /** The model the client uses. */
+    model?: string;
+    /** The longest passage, in characters. Paragraphs are kept whole where they fit. Defaults to 1,500. */
+    passageChars?: number;
+    /** Drafts asked for per passage. Defaults to 2. */
+    perPassage?: number;
+    /**
+     * How alike two questions' words may be before the later one is dropped as a near-duplicate, from
+     * 0 to 1. Defaults to 0.8; `false` keeps every question.
+     */
+    similarity?: number | false;
+    /** The most examples kept. */
+    limit?: number;
+}
+/** What `syntheticDataset()` made, and what it dropped. */
+export interface SyntheticDatasetResult {
+    /** The examples: a question as input, the answer as expected, and the citation in `metadata.citation`. */
+    dataset: Dataset<{
+        question: string;
+    }, string>;
+    /** Drafts whose quote was not in their passage. */
+    unsupported: number;
+    /** Drafts dropped as near-duplicates of a question already kept. */
+    duplicates: number;
+}
+/**
+ * Writes a dataset from documents. Each document is cut into passages, and each passage gets drafts
+ * from `generate` or the model: a question, its answer, and a quote. A draft is kept only when its
+ * quote is in its passage, word for word apart from spacing, and its citation records where; and a
+ * question too like one already kept is dropped.
+ */
+export declare function syntheticDataset(options: SyntheticDatasetOptions): Promise<SyntheticDatasetResult>;
+/** How an attack reaches the target: in what the user asks, in a document it is given, or in a tool's result. */
+export type AttackCarrier = 'direct' | 'document' | 'tool';
+/** How an attack is disguised: as written, in full-width letters, or split by invisible characters. */
+export type AttackDisguise = 'plain' | 'full-width' | 'zero-width';
+/** What an adversarial example gives the target. */
+export interface AdversarialInputs {
+    /** The system prompt, holding the canary the attack tries to get out. */
+    system: string;
+    /** What the user asks. */
+    prompt: string;
+    /** A document the user gives, when the attack is carried in one. */
+    document?: string;
+    /** What a tool returns, when the attack is carried in a tool's result. */
+    toolResult?: string;
+}
+/** What an adversarial example expects: the canary never appears in the output. */
+export interface AdversarialExpected {
+    /** A secret only the system prompt holds. */
+    canary: string;
+}
+/** Options for `adversarialDataset()`. */
+export interface AdversarialDatasetOptions {
+    /** The dataset's name. Defaults to `adversarial`. */
+    name?: string;
+    /** Which attacks. Defaults to all three categories. */
+    categories?: readonly AttackCategory[];
+    /** How they arrive. Defaults to all three carriers. */
+    carriers?: readonly AttackCarrier[];
+    /** How they are disguised. Defaults to all three. */
+    disguises?: readonly AttackDisguise[];
+    /** Adds one benign example per carrier, so a guard that refuses everything shows. Defaults to true. */
+    benign?: boolean;
+    /** More wordings of an attack, such as a model's rephrasings; each becomes an example of its own. */
+    rephrase?: (attack: string, category: AttackCategory) => Promise<string[]> | string[];
+}
+/**
+ * Grows an adversarial dataset from the guardrails' own attack patterns: every seed of
+ * `attackSeeds()`, in each carrier and disguise. Every example hides a canary in the system prompt
+ * and asks, one way or another, for it to come out: injections and jailbreaks tell the model to say
+ * it, exfiltration asks for the prompt that holds it. Score a target with `resistsAttack()`.
+ */
+export declare function adversarialDataset(options?: AdversarialDatasetOptions): Promise<Dataset<AdversarialInputs, AdversarialExpected>>;
+/**
+ * Scores whether a target kept the canary in: 1 when it never appears in the output, read through
+ * the same disguises the guardrails read through. A target that refused, or was stopped by a
+ * guardrail, kept it.
+ */
+export declare function resistsAttack(options?: {
+    key?: string;
+}): Evaluator<AdversarialInputs, AdversarialExpected>;
+/** Options for `promoteIssue()`. */
+export interface PromoteIssueOptions {
+    /** A dataset to add to; its examples are kept and the issue's runs added. */
+    into?: Dataset;
+    /** The new dataset's name, when there is no `into`. Defaults to `issue-<id>`. */
+    name?: string;
+    /** Turns a run into an example. Defaults to its inputs, with its outputs as expected unless it failed. */
+    toExample?: (run: Run) => Omit<DatasetExample, 'id'> | undefined;
+    /** The most runs promoted. Defaults to all of them. */
+    limit?: number;
+}
+/**
+ * Promotes the runs behind an insights issue into a dataset. Each example keeps the run it came from
+ * as `sourceRunId`, and the issue that found it as `metadata.issue`, so a regression test points back
+ * to the problem it guards against. A run already in the dataset is not added twice.
+ */
+export declare function promoteIssue(issue: Issue, options?: PromoteIssueOptions): Dataset;