nexus-ai-pro 2.5.0 → 2.7.0

package/API_STABILITY.md

@@ -41,6 +41,94 @@ 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.
+
+New and stable:
+- `ToolDefinition.stream`, `ToolContext.progress`, and `ToolBody`; `tool()` with `stream`. The
+  AG-UI event name `tool_progress`, and the `progress` and `callId` fields of a tool run's metadata;
+- `McpClient.callTool()`'s `progress` option, and `notifications/progress` from `McpServer`;
+- `AgUiOptions.stateDeltas`, `messagesSnapshot`, and `frontendTools`, and `AgUiPatchOperation`;
+- `CreateAgentOptions.toolSource` and `ToolSourceContext`; `ClientToolDefinition`, the `clientTools`
+  channel, and the `AgentStopReason` member `client_tools`;
+- the `step` member of `GraphEvent`;
+- on `nexus-ai-pro/protocols/a2a`: `A2aTaskStore`, `A2aTaskRecord`, `A2aTaskQuery`,
+  `MemoryA2aTaskStore`, `storeA2aTasks()`; `A2aServerOptions.store`, `pushNotifications`,
+  `extendedCard`, `pollMs`, and `onError`; `A2aPushOptions` and `A2aPushNotificationConfig`; the
+  methods `ListTasks`, `SubscribeToTask`, the four push notification config methods, and
+  `GetExtendedAgentCard`; the client's new methods, `A2aListTasksOptions`, and `A2aTaskPage`; and
+  the error codes `pushNotificationNotSupported` and `extendedCardNotConfigured`.
+
+- on `nexus-ai-pro/protocols/acp`: `AcpSessionStore`, `AcpSessionRecord`, `MemoryAcpSessionStore`,
+  `storeAcpSessions()`, `AcpOptions.sessions` and `editor`, `AcpEditorBridge`, `AcpConnection`,
+  `AcpClientCapabilities`, `session/load`, image and audio blocks, and the fourth argument of
+  `AcpOptions.input`;
+- `nexus-ai-pro/protocols/acp/editor`: `acpEditor()`, `AcpEditor`, `AcpEditorOptions`, and the tool
+  names `editor_read_file`, `editor_write_file`, and `editor_run_command`.
+
+An AG-UI run reports a node's tasks running side by side as one step, and finishes every step it
+started before `RUN_FINISHED` or `RUN_ERROR`. A2A `ListTasks` refuses a status that is not a task
+state, and reads `TASK_STATE_UNSPECIFIED` and `UNRECOGNIZED` as no filter.
+
+A streamed A2A task now reports its move to `TASK_STATE_WORKING` as a status update, before its
+other events.
+
+`GraphEvent` and `AgentStopReason` gain members, as the compatibility rules allow in a minor
+release. Code that switches over either exhaustively should handle the new ones.
+
 ## 2.5 stage (2.5.0)
 
 Everything 2.5 adds is stable from the start and additive.

package/CHANGELOG.md

@@ -4,6 +4,223 @@ 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.
+
+### Added
+
+- **Tool progress, end to end.**
+  - A `ToolDefinition` can have `stream`: an async generator that yields progress and returns the
+    result. `tool()` takes one instead of `execute`, and gives it an `execute` that runs the stream,
+    so it works wherever a tool is executed. `ToolExecutor` runs a stream itself.
+  - `ToolContext.progress` reports progress from any tool. An agent sets it, and turns each report
+    into a `progress` tool event while the tool runs.
+  - Progress reaches the event stream and the server's run events; AG-UI, as a `CUSTOM`
+    `tool_progress` event; A2A, as a working status update with the progress as data; ACP, as an
+    update of the tool call in progress; traces, in the tool run's `metadata.progress`; and the
+    studio's run view.
+  - MCP: `McpServer` runs `stream` tools and sends `notifications/progress` for a call that names a
+    `progressToken`. `McpClient.callTool()` takes a `progress` listener, and the tools from
+    `toNexusTools()` pass a remote tool's progress to the agent.
+
+- **AG-UI, complete**, each part opt-in on `AgUiOptions`:
+  - `stateDeltas` reports state as it changes: a `STATE_SNAPSHOT` after the first step, then a
+    `STATE_DELTA` with an RFC 6902 JSON Patch after every step that changed it, appending to arrays
+    item by item. `AgUiPatchOperation` is its type.
+  - `messagesSnapshot` sends the whole transcript as `MESSAGES_SNAPSHOT` before the run finishes.
+  - `frontendTools` offers the tools the frontend sends to the model. The frontend runs a call to one,
+    and the next run's messages carry its result.
+- **Tools the client runs.** An agent's input may carry `clientTools`, each a `ClientToolDefinition`.
+  The model is offered them; a call to one ends the turn with the new `stopReason: 'client_tools'`
+  once the agent's own calls of that step have run, and the client's result continues it. A client
+  tool never replaces a tool of the agent's own.
+- **Tools that depend on the run.** `CreateAgentOptions.toolSource` supplies tools per run, from a
+  `ToolSourceContext`, offered and run like `tools`, under the same permission policy.
+- **A2A, durable and complete.**
+  - Tasks and conversations live in an `A2aTaskStore`: `MemoryA2aTaskStore` by default, or
+    `storeA2aTasks()` over any long-term `Store`, so a task paused for an answer survives a restart
+    and another replica finishes it.
+  - `ListTasks` by context and state, a page at a time; `SubscribeToTask` on any replica; and a
+    cancel that stands against the replica running the task.
+  - Push notifications, with `pushNotifications`: each state change POSTed to a task's webhook,
+    with the caller's token and signed as the server's operation webhooks are. A webhook must be
+    `https` and not a private address, unless `allowPrivateNetworks` is set.
+  - `GetExtendedAgentCard`, with `extendedCard`, for authenticated callers.
+  - The client gains `extendedCard()`, `listTasks()`, `subscribe()`, `setPushNotification()`,
+    `listPushNotifications()`, `deletePushNotification()`, and `push` and `returnImmediately` when
+    sending.
+- **ACP, durable and complete.**
+  - Sessions live in an `AcpSessionStore`: `MemoryAcpSessionStore` by default, or
+    `storeAcpSessions()` over any long-term `Store`. The agent offers `session/load`, replays the
+    conversation, and asks again a question it was waiting on.
+  - A prompt can carry images and audio, which reach the model as content parts.
+  - `acpEditor()`, on the new `nexus-ai-pro/protocols/acp/editor`, gives an agent the editor's files,
+    terminal, and MCP servers, as tools from its `toolSource`, each declaring what it touches.
+    `serveAcp()` takes it as `editor`, and detaches it when the editor closes its end.
+- **Interoperability, proven.**
+  - A browser in CI: `npm run test:browser` serves the build to headless Chromium, which imports
+    every kernel entry point and runs a graph, an agent, and AG-UI. It runs in `npm test`.
+  - The previous minor on the other side of the wire: a 2.5 client against a 2.6 server, and the
+    other way round, on the server's HTTP API and A2A, and one harness across both releases for
+    AG-UI and ACP.
+  - A nightly `Interoperability` workflow drives each protocol with its reference client:
+    `@ag-ui/client`, `@a2a-js/sdk`, and `@agentclientprotocol/sdk`.
+- **A `step` graph event.** `GraphRunOptions.onEvent` receives `step` after each superstep, with the
+  state after it.
+
+### Fixed
+
+- AG-UI: a run that paused inside a node left that node's step open, so a strict client refused its
+  `RUN_FINISHED`; and a node's tasks running side by side each started the same step. A node's tasks
+  are now one step, and every step still open is finished before the run finishes or fails. Found by
+  the reference client.
+- A2A: `ListTasks` without a status filter, as the reference SDK sends it (`UNRECOGNIZED`), matched
+  no task. An unset filter now filters nothing, and an unknown state is refused as invalid.
+- MCP: the stdio transport's `close()` killed the server without waiting for it, so what the process
+  held, such as its working directory, could outlive the close. It now waits up to two seconds for
+  the process to exit.
+
+### Proof
+
+- Headless Chromium imports every kernel entry point and runs a graph, an agent with a streaming
+  tool, and AG-UI. A 2.5 client and a 2.6 server pass the protocol suites in both directions, and the
+  reference clients of AG-UI, A2A, and ACP each drive this release's servers through a whole run.
+- An ACP session paused on a question survives the agent's restart, on memory and SQLite; the
+  editor reopens it, sees the conversation replayed, and answers. An image and audio reach the model.
+  Through the bridge, an agent reads, writes (after the person allows it), and runs the tests in the
+  editor, and searches docs through an MCP server the editor offered, started as a real process.
+- An A2A task paused for an approval survives a restart and is finished by another replica, sending
+  its email once, on the memory, SQLite, Postgres, and Redis stores. A running task is followed where
+  it runs and from another replica; a cancel on one replica stands against the other. Every state
+  change reaches the webhook, signed and with the caller's token, and nine webhook URLs that point
+  into the agent's own network or are not https are refused.
+- An AG-UI client applying a run's snapshot and its deltas rebuilds the final state exactly, with
+  each new message one `add`. A frontend tool is offered to the model beside the agent's own; the
+  agent runs its own call, waits without calling the model again, and continues from the page's
+  result in the next run. A page cannot shadow the agent's tool, and without the options the events
+  are what they were.
+- A tool that will not go on until a reader has seen its first report finishes on every stream: the
+  event stream, the server's events, AG-UI, A2A, ACP, and MCP. Its reports arrive in order, after the
+  call and before the result, and its traced run keeps them.
+
 ## [2.5.0] - 2026-10-09
 
 Graduation finished, and conversations evaluated.
@@ -2104,7 +2321,9 @@ 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.5.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
 [2.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...v2.3.0

package/README.md

@@ -270,13 +270,22 @@ Shipped so far:
 - 2.5 graduation finished, and conversations evaluated: deployments that change atomically across
   replicas, revision worker pools, fair canaries judged on every run, and the studio out of
   experimental after a threat review; Postgres tenant usage; signed context named on every trace;
-  simulated users and thread evaluators; and a doctor that knows the opt-in settings.
+  simulated users and thread evaluators; and a doctor that knows the opt-in settings;
+- 2.6 protocols complete, and progress on every stream: a tool's progress reaching the event stream,
+  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;
+- 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.6 completes the agent protocols: tool progress on every stream, AG-UI deltas and frontend
-tools, A2A tasks and ACP sessions that survive a restart, and a browser in CI. 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.d.ts

@@ -163,12 +163,44 @@ export interface CreateAgentOptions {
      * event once the model returns. Middleware sees the assembled response either way.
      */
     streamTokens?: boolean;
+    /**
+     * Tools that depend on the run, added to `tools` on every model call and run like them: an editor's
+     * file system for one session, or the MCP servers one user connected. A tool in `tools` wins over a
+     * source's tool of the same name.
+     */
+    toolSource?: (context: ToolSourceContext) => ToolDefinition[] | Promise<ToolDefinition[]>;
+}
+/** What a tool source is told about the run it supplies tools for. */
+export interface ToolSourceContext {
+    /** The run's thread. */
+    threadId: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /** Who the run is for. */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled. */
+    signal: AbortSignal;
+}
+/**
+ * A tool the client runs, such as one an AG-UI frontend offers: a name, a description, and a schema,
+ * with no implementation on the agent's side. Given in the input as `clientTools`, it is offered to
+ * the model like any tool. When the model calls one, the agent ends its turn with `stopReason:
+ * 'client_tools'`, and the client sends the result back in the next run's messages.
+ */
+export interface ClientToolDefinition {
+    /** The name the model calls it by. */
+    name: string;
+    /** What it does, written for the model. */
+    description: string;
+    /** JSON Schema for the arguments. */
+    parameters: Record<string, unknown>;
 }
 declare const agentChannels: () => {
     messages: import("../types/graph.js").Channel<Message[]>;
     iterations: import("../types/graph.js").Channel<number>;
     answer: import("../types/graph.js").Channel<string>;
     stopReason: import("../types/graph.js").Channel<AgentStopReason | undefined>;
+    clientTools: import("../types/graph.js").Channel<ClientToolDefinition[] | undefined>;
 };
 /** The agent's state channels, as a graph schema. */
 export type AgentChannels = ReturnType<typeof agentChannels>;
@@ -182,12 +214,15 @@ export type AgentState = {
     answer: string;
     /** Why the agent stopped. */
     stopReason?: AgentStopReason;
+    /** Tools the client runs, given in the input; see `ClientToolDefinition`. */
+    clientTools?: ClientToolDefinition[];
 };
 /**
  * `completed` when the model answered, `max_iterations` when it ran out of model calls, `stopped`
- * when a middleware ended the run through `context.stop()`.
+ * when a middleware ended the run through `context.stop()`, and `client_tools` when the model called
+ * a tool the client runs, which waits for the client's result.
  */
-export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped';
+export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped' | 'client_tools';
 /** An agent: a compiled graph over the agent's channels. */
 export type AgentGraph = CompiledGraph<AgentChannels>;
 /** Wraps a question into the state an agent starts from. */

package/dist/agent/create-agent.js

@@ -1,13 +1,15 @@
 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(),
     answer: lastValue(''),
     stopReason: lastValue(undefined),
+    clientTools: lastValue(undefined),
 });
 export function agentInput(goal) {
     return { messages: [{ role: 'user', content: goal }] };
@@ -17,19 +19,42 @@ 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) => {
+        if (!options.toolSource)
+            return executor;
+        const supplied = await options.toolSource({
+            threadId: context.threadId,
+            ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
+            ...(context.principal ? { principal: context.principal } : {}),
+            signal: context.signal,
+        });
+        return supplied.length ? searchable(new ToolExecutor([...supplied, ...executor.list()])) : executor;
+    };
     const graph = createGraph({ channels: agentChannels() })
         .addNode('model', async (context) => {
         const state = context.state;
+        const runTools = await toolsFor(context);
+        const clientTools = clientToolsOf(state, runTools);
+        if (clientTools.length > 0 && waitingOnClient(state.messages, clientTools)) {
+            return new Command({ update: { stopReason: 'client_tools' }, goto: END });
+        }
+        const offered = [...runTools.list(), ...clientTools];
         let request = {
             model: options.model ?? 'auto',
             messages: [
                 ...(options.systemPrompt ? [{ role: 'system', content: options.systemPrompt }] : []),
                 ...state.messages,
             ],
-            ...(options.tools?.length ? { tools: executor.list() } : {}),
+            ...(offered.length ? { tools: offered } : {}),
             ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
             ...(options.maxTokens === undefined ? {} : { maxTokens: options.maxTokens }),
             ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
@@ -88,9 +113,28 @@ export function createAgent(options) {
                 goto: END,
             });
         }
+        const forClient = new Set(clientTools.map((item) => item.name));
+        const ours = calls.filter((call) => !forClient.has(call.function.name));
+        for (const call of calls) {
+            if (!forClient.has(call.function.name))
+                continue;
+            const parsed = parseArguments(call.function.arguments);
+            context.tool({
+                phase: 'start',
+                id: call.id,
+                name: call.function.name,
+                args: parsed.ok ? parsed.args : call.function.arguments,
+            });
+        }
+        if (ours.length === 0) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, stopReason: 'client_tools' },
+                goto: END,
+            });
+        }
         return new Command({
             update: { messages: [assistant], iterations: 1 },
-            goto: calls.map((call) => new Send('tools', call)),
+            goto: ours.map((call) => new Send('tools', call)),
         });
     }, { ends: ['tools', END] })
         .addNode('tools', async (context) => {
@@ -100,7 +144,8 @@ export function createAgent(options) {
             return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
         }
         let args = parsed.args;
-        const definition = executor.get(call.function.name);
+        const runTools = await toolsFor(context);
+        const definition = runTools.get(call.function.name);
         const capabilities = capabilitiesOf(definition, args);
         const description = {
             id: call.id,
@@ -149,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({
@@ -159,13 +205,19 @@ export function createAgent(options) {
                 if (recheck.decision === 'deny')
                     return { ok: false, error: `Permission denied: ${recheck.reason}` };
             }
-            return executor.execute(description.name, current.args, {
+            return runTools.execute(description.name, current.args, {
                 toolCallId: call.id,
                 threadId: context.threadId,
                 ...(context.tenantId !== undefined ? { tenantId: context.tenantId } : {}),
                 ...(context.principal ? { principal: context.principal } : {}),
                 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 });
@@ -250,6 +302,25 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+function clientToolsOf(state, runTools) {
+    return (state.clientTools ?? []).filter((item) => typeof item?.name === 'string' && item.name !== '' && !runTools.has(item.name));
+}
+function waitingOnClient(messages, clientTools) {
+    const names = new Set(clientTools.map((item) => item.name));
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (message.role === 'user')
+            return false;
+        if (message.role !== 'assistant' || !message.toolCalls?.length)
+            continue;
+        const answered = new Set(messages
+            .slice(index + 1)
+            .filter((item) => item.role === 'tool')
+            .map((item) => item.toolCallId));
+        return message.toolCalls.some((call) => names.has(call.function.name) && !answered.has(call.id));
+    }
+    return false;
+}
 function hookContext(context, state, store) {
     return {
         state,

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