nexus-ai-pro 2.2.0 → 2.3.0

package/dist/store/memory.js

@@ -4,6 +4,8 @@ export class MemoryStore {
     options;
     items = new Map();
     maxItems;
+    expiring = false;
+    sweptAt = Number.NEGATIVE_INFINITY;
     now;
     constructor(options = {}) {
         this.options = options;
@@ -18,6 +20,8 @@ export class MemoryStore {
         const timestamp = this.now().toISOString();
         const existing = this.items.get(id);
         const vector = await this.embed(value, options.index);
+        if (options.ttlMs !== undefined)
+            this.expiring = true;
         this.items.delete(id);
         this.items.set(id, {
             namespace: [...namespace],
@@ -99,6 +103,12 @@ export class MemoryStore {
         return item.expiresAt !== undefined && Date.parse(item.expiresAt) <= this.now().getTime();
     }
     sweep() {
+        if (!this.expiring)
+            return;
+        const now = this.now().getTime();
+        if (now - this.sweptAt < 1_000 && this.items.size <= this.maxItems)
+            return;
+        this.sweptAt = now;
         for (const [id, item] of this.items)
             if (this.expired(item))
                 this.items.delete(id);

package/dist/types/graph.d.ts

@@ -8,6 +8,7 @@ import type { OperationLifecycleLike } from './lifecycle.js';
  * is, so a different process can pick it up.
  */
 import type { CacheAdapter } from '../cache/adapters.js';
+import type { Principal } from './principal.js';
 import type { Store } from './store.js';
 /** Entry sentinel. An edge from `START` names the first node. */
 export declare const START = "__start__";
@@ -243,6 +244,14 @@ export interface NodeOptions<S extends ChannelSchema = ChannelSchema> {
      * that are not.
      */
     idempotent?: boolean;
+    /**
+     * What the node does to the world, as capabilities: `payments:charge`, `network:api.stripe.com`,
+     * `filesystem:write`. Declared for the linter, which reports a node with effects that also
+     * interrupts, since the node runs again from the top when the answer comes.
+     */
+    effects?: readonly string[];
+    /** True when the node may call `context.interrupt()`. Declared for the linter. */
+    interrupts?: boolean;
     /**
      * Nodes this one may reach through `Send` or a `Command`. Declaring them keeps compile-time
      * reachability checks and diagrams exact, so a node reached only that way is not reported as
@@ -374,6 +383,8 @@ export interface NodeContext<S extends ChannelSchema> {
     readonly threadId: string;
     /** The tenant the run is for, when it has one. */
     readonly tenantId?: string;
+    /** Who the run is for, when it was started with a principal: the caller the server authenticated. */
+    readonly principal?: Readonly<Principal>;
     /** Identifies this task. Equal to `node` unless the task came from a `Send`. */
     readonly taskId: string;
     /** Input carried by a `Send`. Undefined for a node reached through an ordinary edge. */
@@ -577,6 +588,14 @@ export interface GraphRunOptions {
      * `tenantId` is refused before anything runs. A run without one carries on the thread's tenant.
      */
     tenantId?: string;
+    /**
+     * Who the run is for, such as the caller the server authenticated. Nodes read it as
+     * `context.principal`, and an agent hands it to every tool and middleware. Its `tenantId` is the
+     * run's tenant when `tenantId` is not given, and a run whose two tenants differ is refused. Its
+     * `userId` is recorded on every checkpoint as `metadata.userId`; the rest is never stored, so a
+     * resumed run carries the principal of whoever resumed it.
+     */
+    principal?: Principal;
     /** Overrides the compiled `maxConcurrency` for this run. */
     maxConcurrency?: number;
     /** Breakpoints for this run only, replacing the compiled ones. */
@@ -853,6 +872,10 @@ export interface GraphDescription {
         idempotent?: boolean;
         /** True when the node reuses results through `cache`. */
         cache?: boolean;
+        /** The capabilities its work uses, when it declares them. */
+        effects?: string[];
+        /** True when it declares that it may interrupt. */
+        interrupts?: boolean;
         /** The graph this node runs, when it is a compiled graph used through `asNode()`. */
         subgraph?: GraphDescription;
     }>;
@@ -876,6 +899,19 @@ export interface GraphDescription {
     checkpointer?: 'memory' | 'custom' | 'none';
     /** Tasks a superstep runs at once. */
     maxConcurrency?: number;
+    /** The tools the graph's nodes call, when it was compiled with them, as an agent is. */
+    tools?: GraphToolDescription[];
+}
+/** A tool a graph calls, as the linter reads it. */
+export interface GraphToolDescription {
+    /** The tool's name. */
+    name: string;
+    /** Its capabilities, when it declares a fixed list. */
+    capabilities?: string[];
+    /** True when it computes its capabilities from each call's arguments. */
+    dynamic?: boolean;
+    /** How its calls are approved: an interrupt for each, a permission policy, or not at all. */
+    approval: 'interrupt' | 'policy' | 'none';
 }
 /**
  * Options applied when a graph is compiled: stores, breakpoints, concurrency, retries, and failure
@@ -898,6 +934,8 @@ export interface CompileOptions {
     maxConcurrency?: number;
     /** Default retry policy for every node. A node's own policy wins. */
     retry?: RetryPolicy;
+    /** The tools the graph's nodes call, for `describe()` and the linter. `createAgent()` fills it. */
+    tools?: GraphToolDescription[];
     /**
      * Defaults for every node: a retry policy, timeouts, and an `onError`. A node's own options win,
      * field by field. `retry` here is the same as `compile({ retry })`, and wins over it.

package/dist/types/messages.d.ts

@@ -1,5 +1,7 @@
 import type { CacheTtl, ReasoningEffort } from './providers.js';
 import type { AssetInput } from './images.js';
+import type { Principal } from './principal.js';
+import type { Store } from './store.js';
 declare global {
     namespace NodeJS {
         /**
@@ -128,8 +130,19 @@ export interface ToolDefinition {
     description: string;
     /** JSON Schema for the arguments. */
     parameters: Record<string, unknown>;
-    /** Runs the tool, for the agent loop and executors that call tools automatically. */
-    execute?: (args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Runs the tool, for the agent loop and executors that call tools automatically. An agent passes
+     * a `ToolContext` too: who the run is for, its thread and tenant, its signal, and its store.
+     */
+    execute?: (args: Record<string, unknown>, context?: ToolContext) => Promise<unknown>;
+    /**
+     * What the tool does to the world, as capabilities a permission policy decides on:
+     * `filesystem:read` or `filesystem:write` with an optional path, `network` with an optional host,
+     * `shell` with an optional command, `code`, or a name of the application's own such as `payments`.
+     * A function computes them from each call's arguments, so a policy sees the path, host, or command
+     * the call actually uses. Never sent to a model.
+     */
+    capabilities?: readonly string[] | ((args: Record<string, unknown>) => readonly string[]);
     /**
      * Ends a cacheable prefix after this tool. Only honored when the request sets
      * `cache.mode: 'explicit'` and the provider accepts caller-placed breakpoints.
@@ -145,6 +158,27 @@ export interface ToolDefinition {
 export type ToolChoice = 'auto' | 'none' | 'required' | {
     name: string;
 };
+/**
+ * What a tool receives besides its arguments when an agent runs it. Every field is optional: a tool
+ * run outside an agent, or by an executor given nothing, sees none of them.
+ */
+export interface ToolContext {
+    /** The model's id for this call. */
+    toolCallId?: string;
+    /** The thread the run belongs to. */
+    threadId?: string;
+    /** The tenant the run is for. */
+    tenantId?: string;
+    /**
+     * Who the run is for: the caller the server authenticated, with their roles and scopes, so a
+     * tool can act as that user and nobody else.
+     */
+    principal?: Readonly<Principal>;
+    /** Aborted when the run is cancelled or the step times out. A tool that waits should stop with it. */
+    signal?: AbortSignal;
+    /** Long-term memory. In a tenant's run, the tenant's view of it. */
+    store?: Store;
+}
 /** What a tool returned, correlated with the call that asked for it. */
 export interface ToolCallResult {
     /** The id of the call this answers. */

package/dist/types/principal.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Who a request, a run, or a tool call is for.
+ *
+ * One shape everywhere: the server's authentication hook returns it, a run carries it, graph nodes
+ * and workflow steps read it, tools and middleware receive it, and a permission policy can decide on
+ * it. Its tenant scopes threads, runs, budgets, and the store.
+ */
+export interface Principal {
+    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
+    tenantId?: string;
+    /** Who the caller is: a token's subject, a key's owner. Recorded on what they create. */
+    userId?: string;
+    /** What the caller may do. A route that names a scope refuses a principal without it. */
+    scopes?: readonly string[];
+    /** The caller's roles, for policies and tools that decide by role rather than by scope. */
+    roles?: readonly string[];
+    /** How the caller was authenticated: `jwt`, `api-key`, `proxy`, or a name of your own. */
+    method?: string;
+    /** The verified claims or attributes the principal was built from, for anything the fields above leave out. */
+    claims?: Readonly<Record<string, unknown>>;
+}

package/dist/types/principal.js

@@ -0,0 +1 @@
+export {};

package/dist/types/server.d.ts

@@ -6,15 +6,8 @@
  * graph thread, so state, interrupts, and history come from the checkpointer; and an assistant is
  * anything that can stream events for an input, which a compiled graph already does.
  */
-/** Who is making a request, as the server's authentication hook reports them. */
-export interface Principal {
-    /** Isolates threads, runs, and cron jobs. Requests only ever see their own tenant's resources. */
-    tenantId?: string;
-    /** Who the caller is, recorded on what they create. */
-    userId?: string;
-    /** What the caller may do. A route that names a scope refuses a principal without it. */
-    scopes?: readonly string[];
-}
+import type { Principal } from './principal.js';
+export type { Principal };
 /** Where a run stands, as the server reports it. */
 export type RunStatus = 'queued' | 'running' | 'awaiting_input' | 'succeeded' | 'failed' | 'cancelled' | 'expired';
 /** What happens when a run is requested for a thread that is already running one. */

package/dist/utils/tenant.d.ts

@@ -1,3 +1,4 @@
+import type { Principal } from '../types/principal.js';
 /**
  * The tenant id rule every scope shares. An id is letters, digits, `_`, and `-`, so it can never hold
  * the `/` a scoped name or key is built with: no tenant's prefix is a prefix of another's.
@@ -12,3 +13,13 @@ export declare class TenantIdError extends RangeError {
 export declare function assertTenantId(tenantId: string): string;
 /** @internal The prefix a tenant's names and keys carry in a shared store. */
 export declare function tenantPrefix(tenantId: string): string;
+/**
+ * Run options with the principal's tenant applied: the principal's `tenantId` becomes the run's when
+ * it has none, a run whose two tenants differ is refused, and the principal's `userId` is recorded
+ * in the run's metadata.
+ */
+export declare function withPrincipal<O extends {
+    tenantId?: string;
+    principal?: Principal;
+    metadata?: Record<string, unknown>;
+}>(runOptions: O): O;

package/dist/utils/tenant.js

@@ -14,3 +14,17 @@ export function assertTenantId(tenantId) {
 export function tenantPrefix(tenantId) {
     return `tenant/${assertTenantId(tenantId)}/`;
 }
+export function withPrincipal(runOptions) {
+    const principal = runOptions.principal;
+    if (!principal)
+        return runOptions;
+    const tenantId = principal.tenantId;
+    if (tenantId !== undefined && runOptions.tenantId !== undefined && tenantId !== runOptions.tenantId) {
+        throw new TypeError("The run's tenantId and its principal's tenant differ");
+    }
+    return {
+        ...runOptions,
+        ...(tenantId !== undefined && runOptions.tenantId === undefined ? { tenantId } : {}),
+        ...(principal.userId !== undefined ? { metadata: { ...runOptions.metadata, userId: principal.userId } } : {}),
+    };
+}

package/dist/version.d.ts

@@ -2,4 +2,4 @@
  * This package's version, recorded where provenance matters, such as on every experiment. A test
  * keeps it equal to `package.json`.
  */
-export declare const NEXUS_VERSION = "2.2.0";
+export declare const NEXUS_VERSION = "2.3.0";

package/dist/version.js

@@ -1 +1 @@
-export const NEXUS_VERSION = '2.2.0';
+export const NEXUS_VERSION = '2.3.0';

package/dist-cjs/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-cjs/agent/capabilities.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCapability = parseCapability;
+exports.capabilitiesOf = capabilitiesOf;
+exports.isSensitiveCapability = isSensitiveCapability;
+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 };
+}
+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;
+    }
+}
+function isSensitiveCapability(capability) {
+    const parsed = parseCapability(capability);
+    return !(parsed.kind === 'filesystem' && parsed.access === 'read');
+}

package/dist-cjs/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. */