nexus-ai-pro 2.6.0 → 2.7.0

package/API_STABILITY.md

@@ -41,6 +41,58 @@ Both are covered by this policy:
 Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
 one of its explicit subpaths.
 
+## 2.7 stage (2.7.0)
+
+Everything 2.7 adds is stable from the start and additive.
+
+New and stable:
+- on `nexus-ai-pro/agent/sandbox`: `Sandbox.glob()`, `grep()`, and `readBytes()`, all optional;
+  `SandboxGlobOptions`, `SandboxGrepOptions`, and `SandboxMatch`; `SandboxToolsOptions.maxMediaBytes`;
+  and the tool names `glob_files`, `grep_files`, and `read_media`;
+- `DocumentContent` and the `document` member of `ContentPart`, exported from
+  `nexus-ai-pro/runtime`; the `base64` source of `AudioContent`;
+- `nexus-ai-pro/agent/sandbox/container`: `containerSandbox()` and `ContainerSandboxOptions`, with
+  their defaults: no network, every capability dropped, no new privileges, 512 MB of memory and swap,
+  one CPU, and 256 processes;
+- `nexus-ai-pro/agent/interpreter`: `Interpreter`, `InterpreterFunction`, `InterpreterRunOptions`,
+  `InterpreterResult`, `InterpreterCall`, `workerInterpreter()` and `WorkerInterpreterOptions`,
+  `codeTool()` and `CodeToolOptions` with the tool name `run_code`, and `runInterpreterConformance()`
+  with `InterpreterConformanceReport`; `DeepAgentOptions.interpreter`;
+- `DeepAgentOptions.createHelpers` and `maxBackgroundHelpers`, `DeepHelperLimits`, the `background`
+  and `instructions` arguments of `delegate`, the tool name `collect_helper`, the helper thread id
+  `<thread>/helper/<name>@<call id>`, and the helper namespace `<name>@<call id>`;
+- `ToolContext.forward`;
+- `ToolDefinition.deferred` and `tool({ deferred })`; `ToolReferenceContent` and the `tool_reference`
+  member of `ContentPart`, exported from `nexus-ai-pro/runtime`; on `nexus-ai-pro/agent`,
+  `toolSearchTool()`, `ToolSearchOptions`, `searchTools()`, `ToolSearchHit`, and `TOOL_SEARCH_NAME`
+  with the tool name `search_tools`.
+
+- `nexus-ai-pro/evaluate/generate`: `syntheticDataset()` with `SyntheticDatasetOptions`,
+  `SyntheticDocument`, `SyntheticPassage`, `SyntheticDraft`, `SyntheticCitation`, `SyntheticModelClient`,
+  and `SyntheticDatasetResult`; `adversarialDataset()` with `AdversarialDatasetOptions`,
+  `AdversarialInputs`, `AdversarialExpected`, `AttackCarrier`, and `AttackDisguise`; `resistsAttack()`;
+  `promoteIssue()` with `PromoteIssueOptions`;
+- on `nexus-ai-pro/security`: `attackSeeds()`, `AttackSeed`, and `AttackCategory`;
+- `nexus-ai-pro/evaluate/online`: `onlineEvaluationWorker()`, `OnlineEvaluationWorker`,
+  `OnlineEvaluationWorkerOptions`, `OnlineEvaluationWorkerReport`, and `OnlineSchedulePass`; the
+  operation kind `online-evaluation:<source>` and the score mark `value.evaluation`;
+- `EvaluateOptions.budget` and `EvaluationBudgetError` on `nexus-ai-pro/evaluate`.
+
+An agent with no deferred tool offers exactly the tools it did before. Adversarial example ids and
+canaries are stable across runs, so experiments over the same options compare.
+
+A graph run's first checkpoint carries the run's `metadata`, as every later checkpoint already did.
+
+`sandboxTools()` offers the new tools only for a sandbox that implements the methods behind them, so
+a sandbox of the application's own offers the same tools as before. A deep agent over
+`processSandbox()` gets the three new tools and a line of its system prompt naming them.
+
+On OpenAI, a tool message whose media is not only images is followed by a user message that starts
+`Files the tools returned:`; one with only images keeps `Images the tools returned:`.
+
+`ContentPart` and `AudioContent['source']` gain members, as the compatibility rules allow in a minor
+release. Code that switches over either exhaustively should handle the new ones.
+
 ## 2.6 stage (2.6.0)
 
 Everything 2.6 adds is stable from the start and additive.

package/CHANGELOG.md

@@ -4,6 +4,123 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.7.0] - 2026-10-12
+
+Agents that do more, and evaluation that runs on its own.
+
+### Added
+
+- **Workspace search.** A `Sandbox` may implement `glob()`, `grep()`, and `readBytes()`, with
+  `SandboxGlobOptions`, `SandboxGrepOptions`, and `SandboxMatch`. `sandboxTools()` then offers
+  `glob_files` and `grep_files`, bounded at 500 paths and 200 lines, each declaring the directory it
+  reads. `processSandbox()` implements all three: its search follows no links, skips `.git` and
+  `node_modules`, walks at most 20,000 entries, and skips files over 1 MB and binary files.
+- **A multimodal workspace.** `read_media` reads an image, audio, or a PDF in the sandbox as content
+  the model sees, as base64 so it survives a checkpoint, up to `SandboxToolsOptions.maxMediaBytes`
+  (10 MB by default). A deep agent gets all three tools when its sandbox supports them.
+- **Documents and audio reach the model.** The new `DocumentContent` part carries a document, such
+  as a PDF, and `AudioContent` takes base64 text. Anthropic receives a document as a document block,
+  inside a tool result too; OpenAI chat as a file, OpenAI Responses as an input file, and Google as
+  inline data. Audio reaches Google, and OpenAI chat's audio models as `input_audio`. A tool's media
+  follows its results on OpenAI and Google, as its images already did. Any other provider, or a
+  source it cannot read, receives one line naming the part.
+- **A container sandbox**, on the new `nexus-ai-pro/agent/sandbox/container`: `containerSandbox()`
+  drives the `docker` or `podman` binary, with no dependency, one container per sandbox. By default
+  the container has no network, drops every capability, cannot gain privileges, and is held to
+  512 MB, one CPU, and 256 processes; nothing of the host is mounted. A command past its timeout is
+  killed inside the container with everything it started. Files, glob, grep, and media work inside
+  it. `ContainerSandboxOptions` sets the image, binary, working directory, network, and limits.
+- **An interpreter contract**, on the new `nexus-ai-pro/agent/interpreter`. An `Interpreter` runs a
+  snippet that calls the agent's tools as `await tools.<name>(args)`, so many calls take one step.
+  `codeTool()` offers it to a model as `run_code`: it declares `code`, and the policy decides each
+  call the code makes as it decides the model's own, refusing one it would ask a person about.
+  `workerInterpreter()` is the JavaScript reference: a fresh worker per run, a 64 MB heap, a
+  10-second timeout, and caps on calls and logs. It is not a security boundary.
+  `runInterpreterConformance()` checks any interpreter. `DeepAgentOptions.interpreter` adds
+  `run_code` over the deep agent's own tools, and its default policy then grants code.
+- **Helpers beside the deep agent.**
+  - `delegate` takes `background`: it returns a task id at once, and the new `collect_helper` tool
+    returns the answer later, waiting up to `wait_seconds`. `maxBackgroundHelpers` (4) bounds how
+    many work at once.
+  - A background helper keeps checkpoints in the deep agent's checkpointer, on a thread named after
+    the call that started it. After a crash, collecting the task, or repeating the call, carries the
+    same helper on from its last checkpoint.
+  - `createHelpers` lets the agent create a helper from instructions it writes, within
+    `DeepHelperLimits`: the tools, model, model calls, and number per thread.
+  - Streamed with `subgraphs: true`, a helper's events reach the agent's stream under its namespace,
+    such as `tools/researcher@call-7`. `ToolContext.forward` lets any tool do the same for a run it
+    starts.
+- **Tool search.** `ToolDefinition.deferred` (and `tool({ deferred })`) loads a tool only once the
+  model finds it. An agent with a deferred tool offers `search_tools`, which ranks the deferred tools
+  by BM25 over their names, descriptions, and arguments, and answers with `ToolReferenceContent`
+  parts. On Claude 4.5 and later every tool is sent, a deferred one with `defer_loading`, and a
+  found tool loads through a `tool_reference` block, so the tool list never changes; every other
+  model, OpenAI's and Google's included, is sent a deferred tool once it has been found.
+  `toolSearchTool()`, `searchTools()`, and `TOOL_SEARCH_NAME` are on `nexus-ai-pro/agent`.
+- **Datasets that grow**, on the new `nexus-ai-pro/evaluate/generate`:
+  - `syntheticDataset()` writes examples from documents, from your function or a model. Each keeps
+    a citation of the quote that supports it, checked against its passage; unsupported drafts and
+    near-duplicate questions are dropped and counted.
+  - `adversarialDataset()` grows attacks from the guardrails' own patterns, in the user's message, a
+    document, or a tool's result, plain or disguised, each after a canary in the system prompt.
+    `resistsAttack()` scores whether the canary stayed in.
+  - `promoteIssue()` turns an insights issue's runs into examples that keep their run and the issue.
+  - `attackSeeds()` on `nexus-ai-pro/security` returns each injection pattern's example attack.
+- **Online evaluation on workers**, on the new `nexus-ai-pro/evaluate/online`.
+  `onlineEvaluationWorker()` samples runs by a stable hash, queues one operation per run and source
+  on a shared operation store, stops queuing at `maxQueued`, and scores what it claims within a
+  budget ledger. Each score carries a mark naming its operation, so a retry after a crash writes
+  only what is missing, and each run is scored exactly once per source.
+- **A spend cap for experiments.** `evaluate()` takes `budget`. Each example run is reserved and
+  reconciled, and once the budget runs out no further example starts; `evaluate()` rejects with the
+  new `EvaluationBudgetError`, which carries the results it paid for.
+
+### Fixed
+
+- An operation whose store failed under it, such as a database going away while it recorded its
+  result, left its handle pending forever, with an unhandled rejection; the handle now fails with
+  the store's error, and the record's lease lapses for recovery.
+
+### Changed
+
+- A graph run's first checkpoint now carries the run's `metadata`, as every later checkpoint did.
+- A deep agent with helpers offers `collect_helper` beside `delegate`, and its prompt says how to use
+  both; its default policy allows `collect_helper`.
+
+### Proof
+
+- Glob and grep on the reference sandbox: alternatives, `**/` matching no directory, results relative
+  to the root, a limit, a path outside the root refused, a link out of the root not followed, and
+  binary, oversized, vendored, and past-the-line-limit matches skipped.
+- An image, a PDF, and audio from a tool, after a JSON round trip, on the wire of Anthropic, OpenAI
+  chat (with and without an audio model), OpenAI Responses, and Google.
+- A deep agent that greps its workspace, finds a PDF, and reads it as a document.
+- The container sandbox passes the sandbox conformance suite against a real Docker in CI, which now
+  requires one. A command cannot find a host file anywhere in the container, cannot reach the host or
+  the internet, while the same probe from a container with a network can; a command over a 64 MB
+  limit is stopped; and a timeout leaves nothing it started running.
+- The worker interpreter passes the interpreter conformance suite. An agent totals three orders and
+  describes one from code in one model round trip, while the refund in the same code, which the
+  policy asks about, never runs; a deep agent searches and reads its workspace from code, and a
+  command its policy denies is denied from code too.
+- A background helper answers after the agent has moved on, with its events in the agent's stream. A
+  crash while the agent waits for it, and a crash before the agent saved the call that started it,
+  each end with one lookup, one note, and one start of the helper.
+- An agent with 500 deferred tools finishes all 40 tasks on Anthropic, OpenAI, and Google, with a
+  model that calls a tool only once that provider's request has loaded it. Anthropic is sent all 501
+  tools on every call with 500 deferred; OpenAI and Google never more than 11. The search ranks each
+  of the 500 tools first for the step that describes it.
+- A synthetic dataset written from all 39 guides cites, for every example, words that stand in its
+  guide where the citation says; an invented quote and a repeated question are dropped every time.
+  An adversarial dataset of 75 examples gets its canary out of an unguarded agent every time and
+  never out of a guarded one, which still answers the benign examples. Each attack the guardrails
+  block at the input is critical or high, and each medium one is redacted on the way out.
+- Ten online-evaluation workers score 10,000 runs, each score exactly once, while one dies right
+  after writing a run's scores and before recording them; that run is taken back and found already
+  scored, and the queue stays near its limit. Workers on a budget stop at it, leave the rest queued,
+  and carry on the next period without scoring any run twice. Two sources sharing one store never
+  cross, and sampling picks the same runs on every worker. An experiment stops at its budget.
+
 ## [2.6.0] - 2026-10-11
 
 Protocols complete, and progress on every stream.
@@ -2204,7 +2321,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.6.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.7.0...HEAD
+[2.7.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.6.0...v2.7.0
 [2.6.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.5.0...v2.6.0
 [2.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.4.0...v2.5.0
 [2.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...v2.4.0

package/README.md

@@ -275,14 +275,17 @@ Shipped so far:
   the protocols, traces, and the studio; AG-UI state deltas and frontend tools; A2A tasks and ACP
   sessions that survive a restart, with push notifications, `session/load`, and the editor's files,
   terminal, and MCP servers; and every protocol proven in a browser, against the previous release,
-  and against its reference client.
+  and against its reference client;
+- 2.7 agents that do more, and evaluation that runs on its own: workspace search and a multimodal
+  workspace, a container sandbox, an interpreter, helpers that run in the background and survive a
+  crash, and tool search on every provider; datasets generated from documents and from the
+  guardrails' attacks; and online evaluation on workers, within a budget.
 
 Upgrading from 1.x: `npx nexus migrate src --write` moves your imports, and
 [MIGRATING.md](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/MIGRATING.md) covers the rest.
-Next, 2.7 lets agents do more: provider tool search, an interpreter contract, workspace search,
-helpers that run beside the agent, and a container sandbox. Evaluation grows its own datasets and
-runs on workers, within a budget. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
-releases after it.
+Next, the remote vector stores and images graduate once the live workflow passes against each. The
+[roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists what comes after, in the order
+applications ask for it.
 
 ## Before Production
 

package/dist/agent/create-agent.js

@@ -1,8 +1,9 @@
 import { appendList, counter, lastValue } from '../graph/channels.js';
-import { createGraph } from '../graph/graph.js';
+import { createGraph, forwardedEvents } from '../graph/graph.js';
 import { Command, END, Send } from '../types/graph.js';
 import { capabilitiesOf } from './capabilities.js';
 import { ToolExecutor, toolMessageContent } from './tool.js';
+import { TOOL_SEARCH_NAME, toolSearchTool } from './tool-search.js';
 const agentChannels = () => ({
     messages: appendList(),
     iterations: counter(),
@@ -18,7 +19,13 @@ export function createAgent(options) {
         throw new TypeError('createAgent needs a client with a complete() method');
     }
     const maxIterations = Math.max(1, options.maxIterations ?? 8);
-    const executor = new ToolExecutor(options.tools ?? []);
+    const searchable = (tools) => {
+        const deferred = tools.list().filter((definition) => definition.deferred);
+        if (deferred.length === 0 || tools.has(TOOL_SEARCH_NAME))
+            return tools;
+        return new ToolExecutor([...tools.list(), toolSearchTool(deferred)]);
+    };
+    const executor = searchable(new ToolExecutor(options.tools ?? []));
     const middleware = options.middleware ?? [];
     const approvals = options.interruptOn ?? {};
     const toolsFor = async (context) => {
@@ -30,7 +37,7 @@ export function createAgent(options) {
             ...(context.principal ? { principal: context.principal } : {}),
             signal: context.signal,
         });
-        return supplied.length ? new ToolExecutor([...supplied, ...executor.list()]) : executor;
+        return supplied.length ? searchable(new ToolExecutor([...supplied, ...executor.list()])) : executor;
     };
     const graph = createGraph({ channels: agentChannels() })
         .addNode('model', async (context) => {
@@ -187,6 +194,7 @@ export function createAgent(options) {
                 }
             }
         }
+        const forward = forwardedEvents(context);
         const run = async (current) => {
             if (options.permissions && current.args !== args) {
                 const recheck = await options.permissions.decide({
@@ -205,6 +213,11 @@ export function createAgent(options) {
                 signal: context.signal,
                 ...(context.store ? { store: context.store } : {}),
                 progress: (progress) => context.tool({ phase: 'progress', id: call.id, name: description.name, progress }),
+                ...(forward
+                    ? {
+                        forward: (event, namespace) => forward({ ...event, namespace: [...namespace, ...(event.namespace ?? [])] }),
+                    }
+                    : {}),
             });
         };
         context.tool({ phase: 'start', id: call.id, name: description.name, args });

package/dist/agent/glob.d.ts

@@ -0,0 +1,24 @@
+/**
+ * File globs for workspace search, shared by the sandboxes: `*` matches within a path segment, `**`
+ * across segments (`**\/` also matches none), `?` one character, and `{a,b}` either alternative.
+ * Paths use `/`, are relative to the search root, and match case-sensitively.
+ */
+export declare function globMatcher(pattern: string): (path: string) => boolean;
+/** Directories workspace search never enters. */
+export declare const SKIPPED_DIRECTORIES: ReadonlySet<string>;
+/** The most directory entries, or files, one search walks. */
+export declare const WALK_LIMIT = 20000;
+/** Files larger than this are not searched. */
+export declare const GREP_FILE_BYTES = 1048576;
+/** One search reads no more than this, in all. */
+export declare const GREP_TOTAL_BYTES: number;
+/**
+ * The lines of a file that match, numbered from 1 and cut to 300 characters, at most `limit`; none
+ * for a binary file, one with a NUL byte in its first 8,000 bytes.
+ */
+export declare function matchingLines(bytes: Uint8Array, expression: RegExp, limit: number): Array<{
+    line: number;
+    text: string;
+}>;
+/** MIME types for the media a workspace tool reads as content the model sees, by file extension. */
+export declare const MEDIA_TYPES: Readonly<Record<string, string>>;

package/dist/agent/glob.js

@@ -0,0 +1,72 @@
+export function globMatcher(pattern) {
+    const glob = pattern.replace(/\\/g, '/').replace(/^\.\//, '');
+    let source = '';
+    let braces = 0;
+    for (let index = 0; index < glob.length; index += 1) {
+        const char = glob[index];
+        if (char === '*' && glob[index + 1] === '*') {
+            if (glob[index + 2] === '/') {
+                source += '(?:.*/)?';
+                index += 2;
+            }
+            else {
+                source += '.*';
+                index += 1;
+            }
+        }
+        else if (char === '*') {
+            source += '[^/]*';
+        }
+        else if (char === '?') {
+            source += '[^/]';
+        }
+        else if (char === '{') {
+            braces += 1;
+            source += '(?:';
+        }
+        else if (char === '}' && braces > 0) {
+            braces -= 1;
+            source += ')';
+        }
+        else if (char === ',' && braces > 0) {
+            source += '|';
+        }
+        else {
+            source += char.replace(/[.+^$()|[\]\\]/g, '\\$&');
+        }
+    }
+    source += ')'.repeat(braces);
+    const expression = new RegExp(`^${source}$`);
+    return (path) => expression.test(path.replace(/\\/g, '/'));
+}
+export const SKIPPED_DIRECTORIES = new Set(['.git', 'node_modules']);
+export const WALK_LIMIT = 20_000;
+export const GREP_FILE_BYTES = 1_048_576;
+export const GREP_TOTAL_BYTES = 64 * 1_048_576;
+const GREP_LINE_CHARS = 4_000;
+export function matchingLines(bytes, expression, limit) {
+    if (bytes.subarray(0, 8_000).includes(0))
+        return [];
+    const found = [];
+    for (const [index, line] of new TextDecoder().decode(bytes).split(/\r?\n/).entries()) {
+        if (!expression.test(line.slice(0, GREP_LINE_CHARS)))
+            continue;
+        found.push({ line: index + 1, text: line.slice(0, 300) });
+        if (found.length >= limit)
+            break;
+    }
+    return found;
+}
+export const MEDIA_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    pdf: 'application/pdf',
+    wav: 'audio/wav',
+    mp3: 'audio/mp3',
+    flac: 'audio/flac',
+    ogg: 'audio/ogg',
+    aac: 'audio/aac',
+};

package/dist/agent/index.d.ts

@@ -1,5 +1,6 @@
 export { AgentLoop, type AgentModelClient as AgentLoopModelClient } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
+export { searchTools, TOOL_SEARCH_NAME, type ToolSearchHit, type ToolSearchOptions, toolSearchTool, } from './tool-search.js';
 export type { ToolBody } from './tool.js';
 export { limitToolCalls, redactMessages, type RedactOptions, summarizeHistory, type SummarizeOptions, } from './middleware/basic.js';
 export { agentAsTool, agentInput, type AgentApproval, type AgentApprovalPolicy, type AgentChannels, type AgentGraph, type AgentMiddleware, type AgentMiddlewareContext, type AgentModelCallContext, type AgentModelClient, type AgentState, type AgentStopReason, type AgentToolCall, type AgentToolResult, type ClientToolDefinition, createAgent, type CreateAgentOptions, type ToolSourceContext, } from './create-agent.js';

package/dist/agent/index.js

@@ -1,4 +1,5 @@
 export { AgentLoop } from './loop.js';
 export { isToolOutput, tool, ToolExecutor, toolMessageContent, toolOutput } from './tool.js';
+export { searchTools, TOOL_SEARCH_NAME, toolSearchTool, } from './tool-search.js';
 export { limitToolCalls, redactMessages, summarizeHistory, } from './middleware/basic.js';
 export { agentAsTool, agentInput, createAgent, } from './create-agent.js';

package/dist/agent/interpreter.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The interpreter contract: a model writes a snippet of code that calls the agent's tools, and the
+ * snippet runs in one step, instead of one model round trip per call. A loop over fifty records, a
+ * filter on a large result, or three calls at once become one tool call.
+ *
+ * The package ships the contract, a reference that runs code in a worker thread with time and memory
+ * limits, a tool that puts an interpreter in front of a model, and a conformance suite. Like the
+ * reference sandbox, the reference interpreter is not a security boundary: code in a worker can do
+ * anything the process can. Run untrusted code in an interpreter behind a container or a VM.
+ */
+import type { ToolDefinition } from '../types/messages.js';
+import type { PermissionPolicyLike } from './permissions.js';
+/** A function the code calls as `await tools.<name>(args)`. It runs outside the interpreter. */
+export type InterpreterFunction = (args: Record<string, unknown>) => Promise<unknown>;
+/** Options for one run. */
+export interface InterpreterRunOptions {
+    /** The functions the code may call, by name. */
+    tools?: Readonly<Record<string, InterpreterFunction>>;
+    /** Stops the code after this many milliseconds. */
+    timeoutMs?: number;
+    /** Stops the code when aborted. */
+    signal?: AbortSignal;
+}
+/** One call the code made. */
+export interface InterpreterCall {
+    /** The function's name. */
+    name: string;
+    /** Its arguments. */
+    args: unknown;
+    /** Whether it succeeded. */
+    ok: boolean;
+}
+/** What a run did. */
+export interface InterpreterResult {
+    /** True when the code returned; false when it threw, was stopped, or ran out of memory. */
+    ok: boolean;
+    /** What the code returned, when it returned. */
+    value?: unknown;
+    /** What it threw, or why it was stopped. */
+    error?: string;
+    /** What it logged with `console`, one entry per call, cut to the interpreter's limit. */
+    logs: string[];
+    /** The calls it made, in the order it made them. */
+    calls: InterpreterCall[];
+    /** True when it was stopped by its timeout. */
+    timedOut: boolean;
+    /** How long it ran, in milliseconds. */
+    durationMs: number;
+}
+/** Runs code. The application provides one, or uses `workerInterpreter()`. */
+export interface Interpreter {
+    /** Names the interpreter in reports. */
+    readonly name: string;
+    /** The language its code is written in, for the model, such as `JavaScript`. */
+    readonly language: string;
+    /**
+     * Runs code: the body of an async function, which can `await tools.<name>(args)` and `return` a
+     * value. A run never throws; what went wrong is in the result.
+     */
+    run(code: string, options?: InterpreterRunOptions): Promise<InterpreterResult>;
+    /** Releases the interpreter. */
+    dispose?(): Promise<void>;
+}
+/** Options for `workerInterpreter()`. */
+export interface WorkerInterpreterOptions {
+    /** The timeout for a run that sets none. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /** The heap one run may use, in megabytes. Defaults to 64. */
+    memoryMb?: number;
+    /** What one run may log, in characters. Defaults to 64,000. */
+    maxLogChars?: number;
+    /** The most calls one run may make. Defaults to 100. */
+    maxCalls?: number;
+}
+/**
+ * A reference interpreter, for JavaScript: each run gets a fresh worker thread with a heap limit,
+ * stopped at its timeout, so an endless loop or a runaway allocation ends the run, not the process.
+ * Calls to `tools` cross back to the host and run there. It is not a security boundary: the code runs
+ * with the process's own access.
+ */
+export declare function workerInterpreter(options?: WorkerInterpreterOptions): Interpreter;
+/** Options for `codeTool()`. */
+export interface CodeToolOptions {
+    /** The tools the code may call. A tool the agent should not call from code stays out of this list. */
+    tools: readonly ToolDefinition[];
+    /**
+     * Decides each call the code makes, as an agent's policy decides a model's. A call it would ask a
+     * person about is refused instead, since code cannot pause for one; the model can make that call
+     * directly. Without one, every call runs.
+     */
+    permissions?: PermissionPolicyLike;
+    /** The tool's name. Defaults to `run_code`. */
+    name?: string;
+    /** The timeout for one run. Defaults to the interpreter's. */
+    timeoutMs?: number;
+}
+/**
+ * A tool that runs a model's code in an interpreter, with `tools` callable from it, and returns what
+ * the code returned and logged, and the calls it made. It declares `code`, so a permission policy must
+ * grant code before it runs at all; each call the code makes is then decided on its own.
+ */
+export declare function codeTool(interpreter: Interpreter, options: CodeToolOptions): ToolDefinition;
+/** What `runInterpreterConformance()` found. */
+export interface InterpreterConformanceReport {
+    /** The interpreter's name. */
+    interpreter: string;
+    /** True when every check held. */
+    passed: boolean;
+    /** Every check, in order. */
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+/**
+ * Checks a JavaScript interpreter against the contract, without a test framework:
+ *
+ * - code returns a value, logs, and calls tools, in order and at once;
+ * - a tool's failure reaches the code as a rejection it can catch, and an unknown tool fails;
+ * - code that throws is reported, and never throws out of `run()`;
+ * - an endless loop is stopped at the timeout, and the interpreter runs again afterwards;
+ * - a runaway allocation is stopped, and the interpreter runs again afterwards.
+ */
+export declare function runInterpreterConformance(interpreter: Interpreter): Promise<InterpreterConformanceReport>;