nexus-ai-pro 2.2.0 → 2.4.0

package/dist/adapter-kit/index.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The adapter kit: how a package outside this repository builds an adapter — a provider, an
+ * embeddings backend, a vector store, a retriever, or a long-term store — and proves it works.
+ *
+ * Each `define*()` takes what the adapter is, the releases of `nexus-ai-pro` it supports, what it
+ * can do, and how to create it, and returns an adapter whose instances normalize every failure into
+ * an `AdapterError` and report every call for telemetry. Its `verify()` runs the same contract suite
+ * this package runs on its own adapters, skipping only what the adapter declares it cannot do, with a
+ * small benchmark held to the budgets it declares.
+ */
+import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
+import type { BaseProvider } from '../providers/base.js';
+import type { Retriever } from '../rag/retrievers.js';
+import { type EmbeddingProviderConformanceOptions } from '../testing/embedding-provider-conformance.js';
+import { type ProviderConformanceOptions } from '../testing/provider-conformance.js';
+import type { EmbeddingsProvider } from '../types/embeddings.js';
+import type { Store } from '../types/store.js';
+import { type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, type StoreCapabilities, type VectorStoreCapabilities } from './contracts.js';
+import { type AdapterErrorClass } from './errors.js';
+export { ADAPTER_FIXTURE_PASSAGES, type AdapterCheck, type RetrieverCapabilities, type RetrieverContractOptions, runRetrieverContract, runStoreContract, runVectorStoreContract, type StoreCapabilities, type VectorStoreCapabilities, type VectorStoreContractOptions, } from './contracts.js';
+export { AdapterError, type AdapterErrorClass, type AdapterErrorCode, classifyAdapterError } from './errors.js';
+export { parseVersion, satisfiesRange } from './semver.js';
+/** The kinds of adapter the kit builds. */
+export type AdapterKind = 'provider' | 'embeddings' | 'vector-store' | 'retriever' | 'store';
+/** What every adapter declares about itself. */
+export interface AdapterDefinition<Config, Instance, Capabilities> {
+    /** Its name, usually its package name, such as `@acme/nexus-milvus`. */
+    name: string;
+    /** Its own version. */
+    version: string;
+    /** The releases of `nexus-ai-pro` it works with, as a range: `>=2.4.0 <3`. */
+    nexus: string;
+    /** What it can do. The contract skips what it declares it cannot, and fails what it claims and cannot. */
+    capabilities: Capabilities;
+    /** Creates an instance from its configuration. */
+    create(config: Config): Instance | Promise<Instance>;
+    /**
+     * Classifies a failure from the service behind the adapter, when the kit's own reading of statuses
+     * and network codes is not enough. Returning nothing falls back to that reading.
+     */
+    normalizeError?(error: unknown, operation: string): AdapterErrorClass | undefined;
+    /** The p95 latency each operation must stay within in `verify()`'s benchmark, in milliseconds. */
+    budgets?: Readonly<Record<string, number>>;
+}
+/** One call through an adapter, for telemetry. */
+export interface AdapterCallEvent {
+    /** The adapter. */
+    adapter: string;
+    /** Its kind. */
+    kind: AdapterKind;
+    /** The method called, such as `search`. */
+    operation: string;
+    /** How long the call took, in milliseconds. */
+    durationMs: number;
+    /** Whether it succeeded. */
+    ok: boolean;
+    /** How it failed, when it did. */
+    error?: AdapterErrorClass;
+}
+/** Options for an adapter's `create()`. */
+export interface AdapterCreateOptions {
+    /** Receives every call: the hook a tracer, a metrics exporter, or a log subscribes with. */
+    onCall?: (event: AdapterCallEvent) => void;
+}
+/** What `verify()` measured for one operation over the contract's calls. */
+export interface AdapterBenchmarkEntry {
+    /** Successful calls measured. */
+    calls: number;
+    /** Median latency, in milliseconds. */
+    p50Ms: number;
+    /** 95th-percentile latency, in milliseconds. */
+    p95Ms: number;
+}
+/** What `verify()` found. */
+export interface AdapterReport {
+    /** The adapter. */
+    adapter: string;
+    /** Its version. */
+    version: string;
+    /** Its kind. */
+    kind: AdapterKind;
+    /** The `nexus-ai-pro` release it was verified against. */
+    nexusVersion: string;
+    /** Whether that release is inside the adapter's declared range. */
+    compatible: boolean;
+    /** True when it is compatible and every check that ran held. */
+    passed: boolean;
+    /** Every check, in order, with skipped ones marked. */
+    checks: AdapterCheck[];
+    /** Latency per operation over the contract's calls. */
+    benchmark: Record<string, AdapterBenchmarkEntry>;
+}
+/** An adapter built with the kit. */
+export interface Adapter<Config, Instance, Capabilities, VerifyOptions> extends Readonly<Omit<AdapterDefinition<Config, Instance, Capabilities>, 'create'>> {
+    /** Its kind. */
+    readonly kind: AdapterKind;
+    /** Creates an instance whose every call normalizes its failures and reports itself. */
+    create(config: Config, options?: AdapterCreateOptions): Promise<Instance>;
+    /** Whether a release of `nexus-ai-pro` is inside the declared range. Defaults to the installed one. */
+    compatible(nexusVersion?: string): boolean;
+    /** Runs the contract suite for its kind against a fresh instance, with a benchmark. */
+    verify(config: Config, options: VerifyOptions): Promise<AdapterReport>;
+}
+/** What a chat provider supports, which decides the conformance cases it runs. */
+export interface ProviderAdapterCapabilities {
+    /** `stream()`. */
+    streaming: boolean;
+    /** JSON output through `responseFormat`. */
+    json: boolean;
+    /** Tool calls. */
+    tools: boolean;
+    /** `healthCheck()`. */
+    health: boolean;
+}
+/** Options for a provider adapter's `verify()`: the model and, if you like, cases of your own. */
+export type ProviderVerifyOptions = Pick<ProviderConformanceOptions, 'model' | 'fixtures'>;
+/** Builds a chat-provider adapter, verified by the provider conformance suite. */
+export declare function defineProviderAdapter<Config, Instance extends BaseProvider>(definition: AdapterDefinition<Config, Instance, ProviderAdapterCapabilities>): Adapter<Config, Instance, ProviderAdapterCapabilities, ProviderVerifyOptions>;
+/** What an embeddings backend supports. */
+export interface EmbeddingsAdapterCapabilities {
+    /** Stops an embedding call when its signal aborts. */
+    abort: boolean;
+    /** Returns the same vectors for the same input. */
+    deterministic: boolean;
+}
+/** Options for an embeddings adapter's `verify()`. */
+export type EmbeddingsVerifyOptions = Pick<EmbeddingProviderConformanceOptions, 'model' | 'fixtures'>;
+/** Builds an embeddings adapter, verified by the embeddings conformance suite. */
+export declare function defineEmbeddingsAdapter<Config, Instance extends EmbeddingsProvider>(definition: AdapterDefinition<Config, Instance, EmbeddingsAdapterCapabilities>): Adapter<Config, Instance, EmbeddingsAdapterCapabilities, EmbeddingsVerifyOptions>;
+/** Options for a vector-store adapter's `verify()`. */
+export interface VectorStoreVerifyOptions {
+    /** The embedding function the store embeds with, to compute a query vector. */
+    embed: EmbeddingProvider;
+    /** Waits for writes to become searchable, for an eventually consistent index. */
+    settle?: () => Promise<void>;
+}
+/** Builds a vector-store adapter, verified by the `VectorStore` contract. */
+export declare function defineVectorStoreAdapter<Config, Instance extends VectorStore>(definition: AdapterDefinition<Config, Instance, VectorStoreCapabilities>): Adapter<Config, Instance, VectorStoreCapabilities, VectorStoreVerifyOptions>;
+/** Options for a retriever adapter's `verify()`. */
+export type RetrieverVerifyOptions = Omit<RetrieverContractOptions, 'capabilities'>;
+/** Builds a retriever adapter, verified by the `Retriever` contract, and the `SparseRetriever` one when it takes writes. */
+export declare function defineRetrieverAdapter<Config, Instance extends Retriever>(definition: AdapterDefinition<Config, Instance, RetrieverCapabilities>): Adapter<Config, Instance, RetrieverCapabilities, RetrieverVerifyOptions>;
+/** Builds a long-term store adapter, verified by the `Store` contract. */
+export declare function defineStoreAdapter<Config, Instance extends Store>(definition: AdapterDefinition<Config, Instance, StoreCapabilities>): Adapter<Config, Instance, StoreCapabilities, Record<string, never>>;

package/dist/adapter-kit/index.js

@@ -0,0 +1,178 @@
+import { runEmbeddingProviderConformance, } from '../testing/embedding-provider-conformance.js';
+import { runProviderConformance } from '../testing/provider-conformance.js';
+import { NEXUS_VERSION } from '../version.js';
+import { runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
+import { AdapterError, classifyAdapterError } from './errors.js';
+import { satisfiesRange } from './semver.js';
+export { ADAPTER_FIXTURE_PASSAGES, runRetrieverContract, runStoreContract, runVectorStoreContract, } from './contracts.js';
+export { AdapterError, classifyAdapterError } from './errors.js';
+export { parseVersion, satisfiesRange } from './semver.js';
+const OPERATIONS = {
+    provider: ['complete', 'healthCheck'],
+    embeddings: ['embed'],
+    'vector-store': ['add', 'search', 'searchVector', 'delete'],
+    retriever: ['retrieve', 'add', 'delete'],
+    store: ['put', 'get', 'delete', 'search', 'listNamespaces'],
+};
+function build(kind, definition, contract) {
+    for (const field of ['name', 'version', 'nexus']) {
+        if (typeof definition[field] !== 'string' || !definition[field])
+            throw new TypeError(`An adapter needs a ${field}`);
+    }
+    satisfiesRange(NEXUS_VERSION, definition.nexus);
+    const create = async (config, options = {}) => instrument(kind, definition, await definition.create(config), options);
+    return {
+        kind,
+        name: definition.name,
+        version: definition.version,
+        nexus: definition.nexus,
+        capabilities: definition.capabilities,
+        ...(definition.normalizeError ? { normalizeError: definition.normalizeError } : {}),
+        ...(definition.budgets ? { budgets: definition.budgets } : {}),
+        create,
+        compatible: (nexusVersion = NEXUS_VERSION) => satisfiesRange(nexusVersion, definition.nexus),
+        async verify(config, options) {
+            const durations = new Map();
+            const instance = await create(config, {
+                onCall: (event) => {
+                    if (event.ok)
+                        durations.set(event.operation, [...(durations.get(event.operation) ?? []), event.durationMs]);
+                },
+            });
+            const compatible = satisfiesRange(NEXUS_VERSION, definition.nexus);
+            const checks = [
+                {
+                    name: `declares support for nexus-ai-pro ${NEXUS_VERSION}`,
+                    ok: compatible,
+                    ...(compatible ? {} : { detail: `the declared range is ${definition.nexus}` }),
+                },
+                ...(await contract(instance, options, definition.capabilities)),
+            ];
+            const benchmark = {};
+            for (const [operation, values] of durations) {
+                const sorted = [...values].sort((a, b) => a - b);
+                const at = (q) => round(sorted[Math.min(sorted.length - 1, Math.ceil(q * sorted.length) - 1)] ?? 0);
+                benchmark[operation] = { calls: sorted.length, p50Ms: at(0.5), p95Ms: at(0.95) };
+            }
+            for (const [operation, budget] of Object.entries(definition.budgets ?? {})) {
+                const measured = benchmark[operation]?.p95Ms;
+                checks.push(measured === undefined
+                    ? {
+                        name: `${operation} stays within ${budget} ms at p95`,
+                        ok: true,
+                        skipped: true,
+                        detail: 'not called by the contract',
+                    }
+                    : {
+                        name: `${operation} stays within ${budget} ms at p95`,
+                        ok: measured <= budget,
+                        ...(measured <= budget ? {} : { detail: `measured ${measured} ms` }),
+                    });
+            }
+            return {
+                adapter: definition.name,
+                version: definition.version,
+                kind,
+                nexusVersion: NEXUS_VERSION,
+                compatible,
+                passed: checks.every((check) => check.ok),
+                checks,
+                benchmark,
+            };
+        },
+    };
+}
+function instrument(kind, definition, instance, options) {
+    const operations = new Set(OPERATIONS[kind]);
+    return new Proxy(instance, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof property !== 'string' || !operations.has(property) || typeof value !== 'function') {
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            return async (...args) => {
+                const started = performance.now();
+                try {
+                    const result = await value.apply(target, args);
+                    options.onCall?.({
+                        adapter: definition.name,
+                        kind,
+                        operation: property,
+                        durationMs: performance.now() - started,
+                        ok: true,
+                    });
+                    return result;
+                }
+                catch (error) {
+                    const failure = error instanceof AdapterError
+                        ? {
+                            code: error.code,
+                            retryable: error.retryable,
+                            ...(error.status === undefined ? {} : { status: error.status }),
+                        }
+                        : (definition.normalizeError?.(error, property) ?? classifyAdapterError(error));
+                    options.onCall?.({
+                        adapter: definition.name,
+                        kind,
+                        operation: property,
+                        durationMs: performance.now() - started,
+                        ok: false,
+                        error: failure,
+                    });
+                    throw error instanceof AdapterError ? error : new AdapterError(definition.name, property, failure, error);
+                }
+            };
+        },
+    });
+}
+export function defineProviderAdapter(definition) {
+    return build('provider', definition, async (provider, options, capabilities) => {
+        const results = await runProviderConformance(definition.name, provider, {
+            ...options,
+            testStream: capabilities.streaming,
+            testJson: capabilities.json,
+            testTools: capabilities.tools,
+            testHealth: capabilities.health,
+        });
+        return results.flatMap((result) => [
+            {
+                name: `completes the ${result.caseName} case`,
+                ok: result.completeOk,
+                ...(result.completeOk ? {} : { detail: result.error ?? 'the response was not accepted' }),
+            },
+            ...(result.streamOk === undefined ? [] : [{ name: `streams the ${result.caseName} case`, ok: result.streamOk }]),
+            ...(result.healthOk === undefined ? [] : [{ name: 'answers its health check', ok: result.healthOk }]),
+        ]);
+    });
+}
+export function defineEmbeddingsAdapter(definition) {
+    return build('embeddings', definition, async (provider, options, capabilities) => {
+        const results = await runEmbeddingProviderConformance(definition.name, provider, {
+            ...options,
+            testAbort: capabilities.abort,
+            testDeterminism: capabilities.deterministic,
+        });
+        return results.flatMap((result) => [
+            {
+                name: `embeds the ${result.caseName} case`,
+                ok: result.ok,
+                ...(result.ok ? {} : { detail: result.error ?? 'not accepted' }),
+            },
+            ...(result.abortOk === undefined
+                ? []
+                : [{ name: `stops the ${result.caseName} case when aborted`, ok: result.abortOk }]),
+        ]);
+    });
+}
+export function defineVectorStoreAdapter(definition) {
+    return build('vector-store', definition, (store, options, capabilities) => runVectorStoreContract(store, { ...options, capabilities }));
+}
+export function defineRetrieverAdapter(definition) {
+    return build('retriever', definition, (retriever, options, capabilities) => runRetrieverContract(retriever, { ...options, capabilities }));
+}
+export function defineStoreAdapter(definition) {
+    return build('store', definition, (store, _options, capabilities) => runStoreContract(store, { capabilities }));
+}
+function round(value) {
+    return Math.round(value * 100) / 100;
+}

package/dist/adapter-kit/semver.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Version ranges, as an adapter declares the releases of `nexus-ai-pro` it works with. A small,
+ * dependency-free subset of npm's ranges: comparators joined by spaces must all hold, alternatives
+ * joined by `||` need one to hold, and `>=`, `>`, `<=`, `<`, `=`, `^`, `~`, `x`, and `*` mean what
+ * they mean in npm.
+ */
+type Version = [number, number, number];
+/** A version as three numbers. A prerelease or build tag is ignored. `undefined` for anything else. */
+export declare function parseVersion(version: string): Version | undefined;
+/** Whether `version` satisfies `range`, such as `>=2.4.0 <3` or `^2.4.0 || ^3.0.0`. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export {};

package/dist/adapter-kit/semver.js

@@ -0,0 +1,55 @@
+export function parseVersion(version) {
+    const match = /^\s*v?(\d+)\.(\d+)\.(\d+)/.exec(version);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : undefined;
+}
+export function satisfiesRange(version, range) {
+    const parsed = parseVersion(version);
+    if (!parsed)
+        return false;
+    return range.split('||').some((alternative) => {
+        const comparators = alternative.trim().split(/\s+/).filter(Boolean);
+        return comparators.length === 0 || comparators.every((comparator) => holds(parsed, comparator));
+    });
+}
+function holds(version, comparator) {
+    const match = /^(>=|<=|>|<|=|\^|~)?v?(\d+|x|X|\*)(?:\.(\d+|x|X|\*))?(?:\.(\d+|x|X|\*))?/.exec(comparator);
+    if (!match)
+        throw new RangeError(`"${comparator}" is not a version range`);
+    const operator = match[1] ?? '';
+    const parts = [match[2], match[3], match[4]];
+    const fixed = parts.findIndex((part) => part === undefined || /^[xX*]$/.test(part));
+    const known = fixed === -1 ? 3 : fixed;
+    const base = parts.map((part, index) => (index < known ? Number(part) : 0));
+    if (known === 0)
+        return operator === '' || operator === '=' || operator === '>=' || operator === '<=';
+    switch (operator) {
+        case '>=':
+            return compare(version, base) >= 0;
+        case '>':
+            return known === 3 ? compare(version, base) > 0 : compare(version, bump(base, known - 1)) >= 0;
+        case '<=':
+            return known === 3 ? compare(version, base) <= 0 : compare(version, bump(base, known - 1)) < 0;
+        case '<':
+            return compare(version, base) < 0;
+        case '^': {
+            const pinned = base[0] > 0 || known === 1 ? 0 : base[1] > 0 || known === 2 ? 1 : 2;
+            return compare(version, base) >= 0 && compare(version, bump(base, pinned)) < 0;
+        }
+        case '~':
+            return compare(version, base) >= 0 && compare(version, bump(base, known >= 2 ? 1 : 0)) < 0;
+        default:
+            return known === 3
+                ? compare(version, base) === 0
+                : compare(version, base) >= 0 && compare(version, bump(base, known - 1)) < 0;
+    }
+}
+function bump(version, part) {
+    return version.map((value, index) => (index < part ? value : index === part ? value + 1 : 0));
+}
+function compare(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index])
+            return left[index] - right[index];
+    }
+    return 0;
+}

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