nexus-ai-pro 2.2.0 → 2.3.0

package/API_STABILITY.md

@@ -41,6 +41,45 @@ 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.3 stage (2.3.0)
+
+Everything 2.3 adds is stable from the start and additive: no default changes meaning.
+
+- `ToolDefinition.capabilities` and the capability grammar; `permissionPolicy()`, `PermissionPolicy`,
+  `PermissionRules`, `PermissionRequest`, `PermissionVerdict`, `PermissionDecision`,
+  `PermissionPolicyLike`, `parseCapability()`, `capabilitiesOf()`, `isSensitiveCapability()`, and
+  `normalizePath()` (`nexus-ai-pro/agent/permissions`); `CreateAgentOptions.permissions`;
+- the sandbox contract: `Sandbox`, its option, result, and isolation types, `sandboxTools()`,
+  `runSandboxConformance()` and its report types, `SandboxPathError` (`nexus-ai-pro/agent/sandbox`).
+  `processSandbox()` is a development reference and may change; conformance checks may be added;
+- `NodeOptions.effects` and `interrupts`, `CompileOptions.tools`, `GraphToolDescription`, and the lint
+  codes `SENSITIVE_TOOL_WITHOUT_APPROVAL`, `UNDECLARED_TOOL_CAPABILITIES`, and
+  `SIDE_EFFECT_BEFORE_INTERRUPT`;
+- `nexus-ai-pro/agent/middleware` and every middleware and option type on it;
+  `AgentMiddleware.wrapModelCall`, `AgentMiddlewareContext`, `AgentModelCallContext`, the third
+  argument of `wrapToolCall`, `next(call)`, and `AgentStopReason` `'stopped'`. The PII patterns
+  may be tightened in a minor release to cut false positives, and new `PiiKind` members may be
+  added;
+- `nexus-ai-pro/server/auth`: `jwtAuth()`, `apiKeyAuth()`, `trustedProxyAuth()`, `anyAuth()`,
+  `createJwtVerifier()`, `hashApiKey()`, `JwtError` and its codes, and every option type. New
+  `JwtAlgorithm` and `JwtErrorCode` members may be added;
+- `Principal.roles`, `method`, and `claims`; `GraphRunOptions.principal`, `NodeContext.principal`,
+  `WorkflowRunOptions.principal`, and `WorkflowContext.principal`; `ToolContext` and the second
+  argument of `ToolDefinition.execute`; `AgentMiddlewareContext.principal` and
+  `PermissionRequest.principal`. A checkpoint's `metadata.userId` is recorded when a run has a
+  principal with a subject;
+- `SparseRetriever`; `PostgresKeywordIndex` and `keywordIndexMigrations()`
+  (`nexus-ai-pro/postgres/fulltext`); `ElasticsearchKeywordIndex` and `ElasticsearchError`
+  (`nexus-ai-pro/rag/elasticsearch`); and every reranker and option type on
+  `nexus-ai-pro/rag/rerankers`. The default endpoints of hosted rerankers follow their providers'
+  current API versions;
+- `nexus-ai-pro/rag/pipeline`: `createIngestionPipeline()`, `ingestionExecutor()`, and their types.
+  The manifest's layout under `['nexus', 'ingestion', <name>]` is stable: a later release reads a
+  manifest an earlier one wrote;
+- `nexus-ai-pro/deep-agent`: `createDeepAgent()`, `DeepAgentOptions`, `DeepSubagent`, and
+  `DeepSkill`, and the names and arguments of the tools it gives the model (`write_todos`,
+  `delegate`, `load_skill`, `edit_file`). The wording of its system prompt may change in any release.
+
 ## 2.2 stage (2.2.0)
 
 Everything 2.2 adds is stable from the start and additive: no default changes meaning.

package/CHANGELOG.md

@@ -4,6 +4,146 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-10-06
+
+Agents that act safely, on production retrieval.
+
+### Added
+
+- **Capabilities and permission policies.** A tool declares what each call does —
+  `filesystem:write:<path>`, `network:<host>`, `shell:<command>`, `code`, or an effect of the
+  application's own — as a list or a function of its arguments. `permissionPolicy()`, on the new
+  `nexus-ai-pro/agent/permissions`, grants filesystem globs, network hosts, and shell command
+  prefixes, and decides each call: allow, deny, or ask. Paths are normalized before any grant sees
+  them, and a command that chains, pipes, or substitutes is never granted by a prefix.
+  `createAgent({ permissions })` enforces it before a tool runs: a denied call never runs, an `ask`
+  interrupts as `interruptOn` does, and arguments an approver edits are decided again.
+- **A sandbox contract**, on the new `nexus-ai-pro/agent/sandbox`: the `Sandbox` interface a
+  container, VM, or hosted interpreter fills; `sandboxTools()`, whose calls declare exactly the
+  command or path they use; `runSandboxConformance()`, which proves any sandbox against the
+  contract; and `processSandbox()`, a reference for development that is never a security boundary
+  and says so.
+- **The linter reads capabilities.** `SENSITIVE_TOOL_WITHOUT_APPROVAL` reports a tool that writes, runs
+  commands or code, or reaches the network with neither approval nor a policy;
+  `UNDECLARED_TOOL_CAPABILITIES` a tool whose effects cannot be judged; and
+  `SIDE_EFFECT_BEFORE_INTERRUPT` a node that declares `effects` and `interrupts`. An agent's graph
+  describes its tools for it.
+- **A middleware catalog**, on the new `nexus-ai-pro/agent/middleware`, each a separate import:
+  `modelRetry()`, `modelFallback()` (to another model or another client), `dynamicModel()`,
+  `toolRetry()` (which by default repeats only a call that cannot have changed anything),
+  `toolSelector()` (by rule, embedding similarity, or both), `contextEditor()` (clears old tool
+  results in batches, so a prompt cache keeps working), `piiMiddleware()` (validated card numbers
+  and IBANs; redact, mask, hash, or block), `humanApproval()` (per call, in band or out of band),
+  `modelCallLimit()` (per run and per thread, the thread count shared through the store), and
+  `filesystemContext()` (instruction files in, large results out to a file). The three existing
+  middleware are there too.
+- **A wider middleware seam.** `wrapModelCall` wraps the model call itself, and may call `next()`
+  again to retry or fall back. Every hook receives an `AgentMiddlewareContext`: the state, the
+  store, the thread and tenant, the run's signal, and `interrupt()`. `context.stop()` ends a run
+  with an answer and the new `stopReason: 'stopped'`. A `wrapToolCall` can pass `next()` changed
+  arguments, which the permission policy decides again.
+- **Server authentication**, on the new `nexus-ai-pro/server/auth`. It is built on Web Crypto, with no
+  dependency:
+  - `jwtAuth()` takes an identity provider's key set (cached, and refetched when a token names a new
+    key), a public key, or a shared secret, and checks issuer, audience, expiry, and age. It refuses
+    `alg: none` and key confusion, and requires an audience with a key set.
+  - `apiKeyAuth()` compares keys by their SHA-256 hash, from `hashApiKey()`.
+  - `trustedProxyAuth()` refuses to exist without proof that the proxy sent the request.
+  - `anyAuth()` combines hooks.
+  - `createJwtVerifier()` verifies tokens outside the server.
+- **One Principal, everywhere a run goes.** It gains `roles`, `method`, and `claims`.
+  - Graph and workflow runs take a `principal`, which nodes read as `context.principal`. Its tenant
+    becomes the run's, and its subject is recorded on every checkpoint and in the run's trace.
+  - `graphAssistant()` passes the authenticated caller on.
+  - Tools receive a `ToolContext` as the second argument of `execute`: the principal, the thread
+    and tenant, the run's signal, and the tenant's store.
+  - Middleware and permission policies see the principal too.
+- **Sparse retrieval as a contract.** A `SparseRetriever` is keyword search that takes writes, so it
+  fuses with vector search and stays in step with a vector store. `KeywordIndex` is one. Two more
+  ship:
+  - `PostgresKeywordIndex` (`nexus-ai-pro/postgres/fulltext`) uses Postgres full-text search, with a
+    GIN index and ranking in the database. With `shared`, it searches a pgvector table through a
+    generated column, so hybrid search keeps one copy of the data.
+  - `ElasticsearchKeywordIndex` (`nexus-ai-pro/rag/elasticsearch`) works with Elasticsearch or
+    OpenSearch over the REST API, with no client library.
+- **Rerankers**, on the new `nexus-ai-pro/rag/rerankers`, with no SDK:
+  - `cohereReranker()`, `voyageReranker()`, and `jinaReranker()` for hosted APIs;
+  - `teiReranker()` for a self-hosted cross-encoder;
+  - `httpReranker()` for any other API;
+  - `crossEncoderReranker()` for a model run in process.
+- **Durable ingestion**, on the new `nexus-ai-pro/rag/pipeline`. `createIngestionPipeline()` keeps a
+  manifest in any `Store`: each document's content version, its chunking, the embedding model, and
+  each chunk's version. A run:
+  - embeds only new and changed chunks; chunks are named by their text, so one that only moved keeps
+    its embedding;
+  - deletes the chunks and documents that are gone;
+  - keeps keyword indexes in step;
+  - writes to the stores before the manifest.
+
+  `ingestionExecutor()` runs it as a durable operation, and a retry starts at the document the
+  failed attempt stopped on.
+- **A deep-agent preset**, on the new `nexus-ai-pro/deep-agent`. `createDeepAgent()` is
+  `createAgent()` composed with:
+  - a plan, kept in the transcript;
+  - a sandboxed workspace, with `edit_file` for precise changes and commands granted by name;
+  - helpers behind one `delegate` tool, which never get a tool that needs approval;
+  - skills loaded on demand;
+  - instruction files and context offloading;
+  - context editing, optional tool selection, and a default permission policy.
+
+  It returns the same compiled graph as any agent; it is not a new engine.
+- `processSandbox()` loads Node's modules when first used, so `nexus-ai-pro/agent/sandbox`, and a
+  deep agent over a container sandbox, import on any runtime.
+
+### Fixed
+
+- `MemoryStore` swept every item for expiry on every write, so writing n items took time
+  proportional to n². It now sweeps only once an item has a time to live, and at most once a second.
+  Expired items were already hidden from reads.
+
+- `limitToolCalls()` counted calls in memory shared by every run of an agent, so one thread's calls
+  used up another's limit, and the count never reset. It now counts per run from the transcript.
+- A subgraph run through `asNode()` now runs for its parent's tenant, so its store is the tenant's
+  view, as the parent's is.
+- `sandboxTools()` file tools accept a path that names the mount, such as `/workspace/notes.txt`,
+  as well as one relative to it, and say in their descriptions which to use.
+
+### Proof
+
+- In a real agent tool loop, a write outside the workspace and a request to an unlisted host are
+  refused before their tools run, and a granted command that needs approval waits for a person.
+- The process sandbox passes the conformance suite, and a sandbox that leaks the host's environment
+  and writes outside its root fails exactly those two checks.
+- An agent over 150 tools completes 40 tasks, a third of them needing two tools, with
+  `toolSelector()` at equal quality: every task succeeds either way. Input tokens per task fall from
+  about 64,000 to about 5,200, and latency by about 70%: the model's time computed from
+  each request's size, plus the agent's own measured time. Two experiments, reported by
+  `compareExperiments()`, show it.
+- Each middleware is proved in a real agent loop. For example:
+  - a charge that timed out is never retried;
+  - an approver who raises a refund past what the policy allows has the edit refused;
+  - two agents sharing a store share one thread budget;
+  - a 45,000-character tool result reaches the transcript as a preview and a file.
+- A JWT from a test identity provider is verified against its key set and reaches an agent's tool
+  call as a `Principal` with its subject, tenant, roles, and scopes.
+  - The tool's writes land in that tenant's view of the store.
+  - The checkpoint records who ran the step.
+  - Another tenant's token gets 404 for the thread.
+  - Expired, wrong-audience, wrong-issuer, unsigned, and forged tokens are refused.
+  - The provider rotates its key with one refetch.
+- On the stored support dataset, on real Postgres with full-text search and pgvector, hybrid retrieval
+  beats vector-only: recall@5 0.71 → 0.97 and mean reciprocal rank 0.51 → 0.71, both with a 95%
+  interval above zero. A hosted reranker and a local cross-encoder, compared in the same experiment,
+  each lift mean reciprocal rank to 0.97. One contract test runs against all four keyword indexes.
+- An ingestion of 100,000 documents dies halfway inside a durable operation. Its retry starts at the
+  document the first attempt stopped on, and embeds no chunk that had finished. A second run after
+  ten documents are edited embeds exactly ten chunks and deletes their old versions.
+- A deep agent completes a multi-step task on a fixture repository inside the reference sandbox. It
+  plans, runs the failing test, reads and edits the bug, verifies the fix, has a helper review it,
+  loads a skill, and records the change; the test then passes outside the agent. Along the way, a
+  30,000-character log is offloaded to a file. The default policy refuses an unlisted command, a
+  chained command, a write outside the workspace, and an ungranted tool.
+
 ## [2.2.0] - 2026-10-05
 
 Production scale and safe upgrades. Every database schema is versioned, so an upgrade applies only
@@ -1637,7 +1777,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.2.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.3.0...HEAD
+[2.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.25.0...v2.0.0

package/README.md

@@ -8,7 +8,7 @@ team can share.
 Import only what you use. The root import is the client and nothing else, and every other capability
 has its own entry point with a size budget CI enforces; [the packaging guide](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/packaging.md)
 publishes what each one costs. The package has no required dependencies: a graph-only application
-loads 78 KB, and installs nothing but this package.
+loads 80 KB, and installs nothing but this package.
 
 - NPM: https://www.npmjs.com/package/nexus-ai-pro
 - GitHub: https://github.com/mkhitar-abrahamyan/nexus-ai
@@ -132,7 +132,8 @@ from the doc comments. The guides live in the repository, so these links go to G
 | [Providers and routing](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/providers.md) | The twelve completion providers, routing and failover, the model registry |
 | [Guardrails](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/security.md) | Injection, PII, secrets, schema validation, output redaction |
 | [Graphs](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/graphs.md) | Parallel branches, interrupts, checkpoints, time travel, subgraphs, caching, diagrams |
-| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals and middleware, and the simple tool loop |
+| [Agents and tools](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/agents.md) | Graph-based agents with approvals, capabilities and permission policies, a sandbox contract, the middleware catalog, and the simple tool loop |
+| [The deep-agent preset](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/deep-agents.md) | Long, multi-step agents: a plan, a sandboxed workspace, helpers, skills, and a context that stays small |
 | [Long-term memory](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/memory.md) | Namespaced memory with semantic search, in memory or Redis |
 | [MCP](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/mcp.md) | Borrowing tools from MCP servers, a registry of many, and serving your own |
 | [Traces](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/docs/tracing.md) | Run trees, queries, feedback, comparison, and alerts |
@@ -251,12 +252,16 @@ Shipped so far:
   backend, one event stream, and dashboard rollups;
 - 2.2 production scale and safe upgrades: versioned database migrations, queue claims and routing
   that cost the same at any size, a circuit breaker that counts across workers, one tenant model
-  across every store, and `nexus doctor` to check a deployment before it serves traffic.
+  across every store, and `nexus doctor` to check a deployment before it serves traffic;
+- 2.3 agents that act safely, on production retrieval: capabilities and permission policies, a
+  sandbox contract, a middleware catalog, server authentication with one principal on every run,
+  keyword search in Postgres and Elasticsearch with rerankers, durable ingestion, and a deep-agent
+  preset.
 
 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.3 gives agents a real security boundary — capabilities, permissions, and a sandbox contract —
-with a complete middleware catalog, and retrieval that works at production scale. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
+Next, 2.4 takes the experimental surfaces out of experimental with evidence, adds an adapter kit, and
+speaks the agent protocols beyond MCP from a portable kernel. The [roadmap](https://github.com/mkhitar-abrahamyan/nexus-ai/blob/main/ROADMAP.md) lists the
 releases after it.
 
 ## Before Production

package/dist/agent/capabilities.d.ts

@@ -0,0 +1,39 @@
+import type { ToolDefinition } from '../types/messages.js';
+/**
+ * Capabilities: what a tool does to the world, written as strings a policy can decide on.
+ *
+ * | Capability | Means |
+ * | --- | --- |
+ * | `filesystem:read`, `filesystem:read:<path>` | Reads files, or one path |
+ * | `filesystem:write`, `filesystem:write:<path>` | Writes, creates, or deletes files |
+ * | `network`, `network:<host or URL>` | Opens a network connection, to a host when given |
+ * | `shell`, `shell:<command line>` | Runs a shell command |
+ * | `code` | Runs code it was given, as an interpreter does |
+ * | `<name>`, `<name>:<detail>` | Anything the application names, such as `payments:refund` |
+ *
+ * A tool that declares `capabilities: []` does nothing to the world; one that declares none at all
+ * is undeclared, and a policy decides on it as such.
+ */
+/** One capability, split into its parts. */
+export interface ParsedCapability {
+    /** `filesystem`, `network`, `shell`, `code`, or the application's own name. */
+    kind: string;
+    /** `read` or `write`, for the filesystem. */
+    access?: 'read' | 'write';
+    /** The path, host, command, or detail, when the capability names one. */
+    target?: string;
+}
+/** Splits a capability string into its kind, access, and target. */
+export declare function parseCapability(capability: string): ParsedCapability;
+/**
+ * The capabilities one call of a tool declares: its static list, or what its function computes from
+ * the call's arguments. `undefined` means undeclared — no list, or a function that threw — which is
+ * not the same as `[]`, a tool that declares it does nothing to the world.
+ */
+export declare function capabilitiesOf(tool: Pick<ToolDefinition, 'capabilities'> | undefined, args: Record<string, unknown>): string[] | undefined;
+/**
+ * Whether a capability is sensitive: anything but reading files. A pure tool declares
+ * `capabilities: []`; whatever it does declare, a write, a command, code, the network, or an
+ * effect of the application's own such as `payments`, changes the world or leaves the process.
+ */
+export declare function isSensitiveCapability(capability: string): boolean;

package/dist/agent/capabilities.js

@@ -0,0 +1,36 @@
+export function parseCapability(capability) {
+    const text = capability.trim();
+    const colon = text.indexOf(':');
+    const kind = (colon < 0 ? text : text.slice(0, colon)).toLowerCase();
+    const rest = colon < 0 ? undefined : text.slice(colon + 1);
+    if (kind === 'filesystem') {
+        if (!rest)
+            return { kind };
+        const [access, ...path] = rest.split(':');
+        const parsed = { kind };
+        if (access === 'read' || access === 'write')
+            parsed.access = access;
+        const target = parsed.access ? path.join(':') : rest;
+        if (target)
+            parsed.target = target;
+        return parsed;
+    }
+    return rest === undefined || rest === '' ? { kind } : { kind, target: rest };
+}
+export function capabilitiesOf(tool, args) {
+    const declared = tool?.capabilities;
+    if (!declared)
+        return undefined;
+    if (typeof declared !== 'function')
+        return [...declared];
+    try {
+        return [...declared(args)];
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isSensitiveCapability(capability) {
+    const parsed = parseCapability(capability);
+    return !(parsed.kind === 'filesystem' && parsed.access === 'read');
+}

package/dist/agent/create-agent.d.ts

@@ -1,9 +1,11 @@
 import type { OperationLifecycleLike } from '../types/lifecycle.js';
 import { type CompiledGraph } from '../graph/graph.js';
-import type { GraphCheckpointer, NodeContext } from '../types/graph.js';
+import type { GraphCheckpointer, InterruptRequest, NodeContext } from '../types/graph.js';
 import type { CompletionRequest, Message, ToolDefinition } from '../types/messages.js';
 import type { NexusResponse, StreamChunk } from '../types/response.js';
+import type { Principal } from '../types/principal.js';
 import type { Store } from '../types/store.js';
+import type { PermissionPolicyLike } from './permissions.js';
 /**
  * An agent as a graph.
  *
@@ -28,6 +30,10 @@ export interface AgentToolCall {
     name: string;
     /** Arguments, parsed from the model's JSON. */
     args: Record<string, unknown>;
+    /** What the call declares it does, when the tool declares capabilities. */
+    capabilities?: readonly string[];
+    /** Why the permission policy asked for approval, when it did. */
+    permission?: string;
 }
 /** What an approver may answer: allow, refuse with a reason, or allow with corrected arguments. */
 export type AgentApproval = boolean | {
@@ -42,24 +48,58 @@ export interface AgentApprovalPolicy {
     /** The question an operator sees. Defaults to naming the tool and its arguments. */
     reason?: (call: AgentToolCall) => string;
 }
+/** What every middleware hook can read about the step it runs in. */
+export interface AgentMiddlewareContext {
+    /** The agent's state at this step: the whole transcript, tool calls and results included. */
+    state: AgentState;
+    /** Long-term memory, when the agent has a store. */
+    store?: Store;
+    /** The thread the run belongs to. */
+    threadId: string;
+    /** The tenant the run is for, when it has one. */
+    tenantId?: string;
+    /** Who the run is for, when it has a principal: the caller the server authenticated. */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled or the step times out. A hook that waits should stop with it. */
+    signal: AbortSignal;
+    /**
+     * Suspends the run until a person answers, as `interruptOn` does. When the run resumes, the step
+     * runs again and this returns the answer instead of suspending.
+     */
+    interrupt<T = unknown>(request: InterruptRequest): T;
+}
+/** What `wrapModelCall` can read, and how it ends the run without calling the model. */
+export interface AgentModelCallContext extends AgentMiddlewareContext {
+    /**
+     * Ends the run with this answer and `stopReason: 'stopped'`, without another model call. Return
+     * what it returns: `return context.stop('The model call limit was reached.')`.
+     */
+    stop(answer: string): NexusResponse;
+}
 /** Hooks around the agent's model calls and tool calls. Each hook is optional. */
 export interface AgentMiddleware {
     /** Names the middleware in traces and errors. */
     name?: string;
     /** Adjusts the request before it is sent: trim history, add context, swap the model. */
-    beforeModel?(context: {
+    beforeModel?(context: AgentMiddlewareContext & {
         request: CompletionRequest;
-        state: AgentState;
-        store?: Store;
     }): CompletionRequest | void | Promise<CompletionRequest | void>;
     /** Inspects or replaces the response: redact, validate, count. */
-    afterModel?(context: {
+    afterModel?(context: AgentMiddlewareContext & {
         response: NexusResponse;
-        state: AgentState;
-        store?: Store;
     }): NexusResponse | void | Promise<NexusResponse | void>;
-    /** Wraps a tool call, so a policy can log it, time it, or refuse it. */
-    wrapToolCall?(call: AgentToolCall, next: () => Promise<AgentToolResult>): Promise<AgentToolResult> | AgentToolResult;
+    /**
+     * Wraps the model call itself, after every `beforeModel` and before every `afterModel`. `next`
+     * sends a request and may be called again, with the same request or a changed one, to retry or to
+     * fall back to another model. The first middleware is the outermost.
+     */
+    wrapModelCall?(request: CompletionRequest, next: (request: CompletionRequest) => Promise<NexusResponse>, context: AgentModelCallContext): Promise<NexusResponse> | NexusResponse;
+    /**
+     * Wraps a tool call, so a policy can log it, time it, retry it, or refuse it. `next` runs the
+     * rest of the chain and may be called again; given a call, it runs that call's arguments instead,
+     * and the permission policy decides them again first. The first middleware is the outermost.
+     */
+    wrapToolCall?(call: AgentToolCall, next: (call?: AgentToolCall) => Promise<AgentToolResult>, context: AgentMiddlewareContext): Promise<AgentToolResult> | AgentToolResult;
 }
 /** What a tool call produced. */
 export interface AgentToolResult {
@@ -88,6 +128,13 @@ export interface CreateAgentOptions {
     interruptOn?: Record<string, AgentApprovalPolicy | true>;
     /** Hooks around model and tool calls, applied in order. */
     middleware?: AgentMiddleware[];
+    /**
+     * Decides every tool call from the capabilities it declares, before it runs: allow it, deny it,
+     * or interrupt for a person's approval, as `interruptOn` does. A denied call reaches the model as a
+     * failed tool result naming the reason, and never runs. See `permissionPolicy()` in
+     * `nexus-ai-pro/agent/permissions`.
+     */
+    permissions?: PermissionPolicyLike;
     /** Long-term memory, available to tools and middleware as `store`. */
     store?: Store;
     /**
@@ -136,8 +183,11 @@ export type AgentState = {
     /** Why the agent stopped. */
     stopReason?: AgentStopReason;
 };
-/** `completed` when the model answered, `max_iterations` when it ran out of model calls. */
-export type AgentStopReason = 'completed' | 'max_iterations';
+/**
+ * `completed` when the model answered, `max_iterations` when it ran out of model calls, `stopped`
+ * when a middleware ended the run through `context.stop()`.
+ */
+export type AgentStopReason = 'completed' | 'max_iterations' | 'stopped';
 /** 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,6 +1,7 @@
 import { appendList, counter, lastValue } from '../graph/channels.js';
 import { createGraph } from '../graph/graph.js';
 import { Command, END, Send } from '../types/graph.js';
+import { capabilitiesOf } from './capabilities.js';
 import { ToolExecutor, toolMessageContent } from './tool.js';
 const agentChannels = () => ({
     messages: appendList(),
@@ -34,24 +35,47 @@ export function createAgent(options) {
             ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
             ...(options.metadata ? { metadata: options.metadata } : {}),
         };
+        const hooks = hookContext(context, state, options.store);
         for (const item of middleware) {
-            request = (await item.beforeModel?.({ request, state, store: options.store })) ?? request;
+            request = (await item.beforeModel?.({ ...hooks, request })) ?? request;
         }
-        let response = options.streamTokens && options.client.stream
-            ? await streamed(options.client.stream(request), (chunk) => context.message(chunk))
-            : await options.client.complete(request);
-        if (!(options.streamTokens && options.client.stream) && response.content) {
+        const streaming = Boolean(options.streamTokens && options.client.stream);
+        const send = (next) => streaming && options.client.stream
+            ? streamed(options.client.stream(next), (chunk) => context.message(chunk))
+            : options.client.complete(next);
+        const stops = new WeakSet();
+        const modelContext = {
+            ...hooks,
+            stop: (answer) => {
+                const stopped = stopResponse(answer, request.model);
+                stops.add(stopped);
+                return stopped;
+            },
+        };
+        const wrapped = middleware.reduceRight((next, item) => {
+            const wrap = item.wrapModelCall?.bind(item);
+            return wrap ? (current) => Promise.resolve(wrap(current, next, modelContext)) : next;
+        }, send);
+        let response = await wrapped(request);
+        const stopped = stops.has(response);
+        if ((!streaming || stopped) && response.content) {
             context.message({ content: response.content });
         }
         for (const item of middleware) {
-            response = (await item.afterModel?.({ response, state, store: options.store })) ?? response;
+            response = (await item.afterModel?.({ ...hooks, response })) ?? response;
         }
         const assistant = {
             role: 'assistant',
             content: response.content,
-            ...(response.toolCalls?.length ? { toolCalls: response.toolCalls } : {}),
+            ...(response.toolCalls?.length && !stopped ? { toolCalls: response.toolCalls } : {}),
         };
-        const calls = response.toolCalls ?? [];
+        const calls = stopped ? [] : (response.toolCalls ?? []);
+        if (stopped) {
+            return new Command({
+                update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'stopped' },
+                goto: END,
+            });
+        }
         if (calls.length === 0) {
             return new Command({
                 update: { messages: [assistant], iterations: 1, answer: response.content, stopReason: 'completed' },
@@ -76,27 +100,82 @@ export function createAgent(options) {
             return { messages: [toolMessage(call, { ok: false, error: parsed.error })] };
         }
         let args = parsed.args;
-        const description = { id: call.id, name: call.function.name, args };
+        const definition = executor.get(call.function.name);
+        const capabilities = capabilitiesOf(definition, args);
+        const description = {
+            id: call.id,
+            name: call.function.name,
+            args,
+            ...(capabilities ? { capabilities } : {}),
+        };
+        const refuse = (error) => {
+            context.tool({ phase: 'error', id: call.id, name: description.name, error });
+            return { messages: [toolMessage(call, { ok: false, error })] };
+        };
+        let permission;
+        if (options.permissions) {
+            const verdict = await options.permissions.decide({
+                tool: description.name,
+                args,
+                capabilities,
+                ...(context.principal ? { principal: context.principal } : {}),
+            });
+            if (verdict.decision === 'deny')
+                return refuse(`Permission denied: ${verdict.reason}`);
+            if (verdict.decision === 'ask')
+                permission = verdict.reason;
+        }
         const policy = approvals[description.name];
-        if (policy) {
+        if (policy || permission) {
+            const asked = permission ? { ...description, permission } : description;
             const decision = context.interrupt({
-                reason: (policy === true ? undefined : policy.reason?.(description)) ?? defaultReason(description),
-                payload: description,
+                reason: (policy && policy !== true ? policy.reason?.(asked) : undefined) ??
+                    (permission ? `${defaultReason(asked)} (${permission})` : defaultReason(asked)),
+                payload: asked,
             });
             const verdict = normalizeApproval(decision);
-            if (!verdict.approved) {
-                return {
-                    messages: [toolMessage(call, { ok: false, error: verdict.reason ?? 'A human refused this tool call' })],
-                };
-            }
-            if (verdict.args)
+            if (!verdict.approved)
+                return refuse(verdict.reason ?? 'A human refused this tool call');
+            if (verdict.args) {
                 args = verdict.args;
+                if (options.permissions) {
+                    const recheck = await options.permissions.decide({
+                        tool: description.name,
+                        args,
+                        capabilities: capabilitiesOf(definition, args),
+                    });
+                    if (recheck.decision === 'deny')
+                        return refuse(`Permission denied: ${recheck.reason}`);
+                }
+            }
         }
-        const run = async () => executor.execute(description.name, args);
+        const run = async (current) => {
+            if (options.permissions && current.args !== args) {
+                const recheck = await options.permissions.decide({
+                    tool: description.name,
+                    args: current.args,
+                    capabilities: capabilitiesOf(definition, current.args),
+                });
+                if (recheck.decision === 'deny')
+                    return { ok: false, error: `Permission denied: ${recheck.reason}` };
+            }
+            return executor.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 } : {}),
+            });
+        };
         context.tool({ phase: 'start', id: call.id, name: description.name, args });
-        const result = await middleware.reduceRight((next, item) => item.wrapToolCall
-            ? () => Promise.resolve(item.wrapToolCall?.({ ...description, args }, next))
-            : next, run)();
+        const hooks = hookContext(context, context.state, options.store);
+        const result = await middleware.reduceRight((next, item) => {
+            const wrap = item.wrapToolCall?.bind(item);
+            return wrap
+                ? (current) => Promise.resolve(wrap(current, (changed) => next(changed ?? current), hooks))
+                : next;
+        }, run)({ ...description, args });
         context.tool(result.ok
             ? { phase: 'result', id: call.id, name: description.name, result: result.result }
             : { phase: 'error', id: call.id, name: description.name, error: result.error ?? 'The tool failed' });
@@ -111,6 +190,12 @@ export function createAgent(options) {
         ...(options.store ? { store: options.store } : {}),
         ...(options.name ? { name: options.name } : {}),
         ...(options.lifecycle ? { lifecycle: options.lifecycle, lifecycleFamily: 'agent' } : {}),
+        tools: executor.list().map((definition) => ({
+            name: definition.name,
+            ...(Array.isArray(definition.capabilities) ? { capabilities: [...definition.capabilities] } : {}),
+            ...(typeof definition.capabilities === 'function' ? { dynamic: true } : {}),
+            approval: approvals[definition.name] ? 'interrupt' : options.permissions ? 'policy' : 'none',
+        })),
     });
 }
 export function agentAsTool(options) {
@@ -165,6 +250,35 @@ function parseArguments(raw) {
         return { ok: false, error: `Tool arguments are not valid JSON (${reason}); the tool was not run` };
     }
 }
+function hookContext(context, state, store) {
+    return {
+        state,
+        ...((context.store ?? store) ? { store: context.store ?? store } : {}),
+        threadId: context.threadId,
+        ...(context.tenantId ? { tenantId: context.tenantId } : {}),
+        ...(context.principal ? { principal: context.principal } : {}),
+        signal: context.signal,
+        interrupt: (request) => context.interrupt(request),
+    };
+}
+function stopResponse(answer, model) {
+    return {
+        content: answer,
+        role: 'assistant',
+        finishReason: 'stop',
+        meta: {
+            requestId: '',
+            providerUsed: 'none',
+            modelUsed: model,
+            latencyMs: 0,
+            tokensInput: 0,
+            tokensOutput: 0,
+            tokensSaved: 0,
+            cacheHit: false,
+            guardrailsApplied: ['stopped-by-middleware'],
+        },
+    };
+}
 async function streamed(chunks, onChunk) {
     let content = '';
     const toolCalls = [];