nexus-ai-pro 2.2.0 → 2.4.0

package/dist-cjs/server/server.js

@@ -140,6 +140,11 @@ function createAgentServer(options) {
         const body = await (0, http_js_1.readJson)(request);
         return (0, http_js_1.json)(await runs.cancel(params.runId, principal, body.reason));
     });
+    write('POST', '/runs/:runId/feedback', async ({ request, params, principal }) => {
+        const body = await (0, http_js_1.readJson)(request);
+        const run = await runs.addFeedback(params.runId, { ...body, source: body.source ?? principal?.userId ?? 'api' }, principal);
+        return (0, http_js_1.json)({ runId: run.id, feedback: run.feedback?.at(-1) }, 201);
+    });
     read('GET', '/runs/:runId/events', async ({ request, params, principal, url }) => {
         await runs.run(params.runId, principal);
         const header = request.headers.get('last-event-id') ?? url.searchParams.get('lastEventId');

package/dist-cjs/store/memory.d.ts

@@ -20,6 +20,10 @@ export declare class MemoryStore implements Store {
     private readonly options;
     private readonly items;
     private readonly maxItems;
+    /** Whether any item was ever given a time to live; until one is, there is nothing to sweep. */
+    private expiring;
+    /** When expired items were last swept, in milliseconds. */
+    private sweptAt;
     private readonly now;
     constructor(options?: MemoryStoreOptions);
     /** Stores an item, keeping its original `createdAt` when it replaces one. */
@@ -42,5 +46,11 @@ export declare class MemoryStore implements Store {
     size(): number;
     private embed;
     private expired;
+    /**
+     * Drops expired items. Reads already skip them, so this only reclaims memory: it runs once any item
+     * has a time to live, and at most once a second, so a write stays constant-time however many items
+     * there are. A store that is full sweeps before it evicts, so a live item never makes way for an
+     * expired one.
+     */
     private sweep;
 }

package/dist-cjs/store/memory.js

@@ -11,6 +11,8 @@ class MemoryStore {
     options;
     items = new Map();
     maxItems;
+    expiring = false;
+    sweptAt = Number.NEGATIVE_INFINITY;
     now;
     constructor(options = {}) {
         this.options = options;
@@ -25,6 +27,8 @@ 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],
@@ -106,6 +110,12 @@ 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-cjs/testing/record.js

@@ -9,7 +9,7 @@ exports.replayFetch = replayFetch;
 exports.fixtureFetch = fixtureFetch;
 exports.installFetch = installFetch;
 exports.readFixtures = readFixtures;
-const node_crypto_1 = require("node:crypto");
+const sha256_js_1 = require("../utils/sha256.js");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 class FixtureMissingError extends Error {
@@ -160,7 +160,7 @@ function defaultKey(input, ignoreBodyFields = []) {
     }
     catch {
     }
-    return (0, node_crypto_1.createHash)('sha256').update(`${input.method}\n${input.url}\n${body}`).digest('hex').slice(0, 16);
+    return (0, sha256_js_1.sha256Hex)(`${input.method}\n${input.url}\n${body}`).slice(0, 16);
 }
 function canonical(value) {
     if (Array.isArray(value))

package/dist-cjs/tracing/stores.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonlTraceStore = exports.MemoryTraceStore = exports.assembleTree = exports.applyQuery = void 0;
 exports.closeAbandonedRuns = closeAbandonedRuns;
+const ids_js_1 = require("../utils/ids.js");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const query_js_1 = require("./query.js");
@@ -141,7 +142,7 @@ class JsonlTraceStore {
         catch {
             return;
         }
-        if (Buffer.byteLength(content, 'utf8') <= this.maxBytes)
+        if ((0, ids_js_1.utf8Length)(content) <= this.maxBytes)
             return;
         const lines = content.split('\n').filter(Boolean);
         await (0, promises_1.writeFile)(this.file, `${lines.slice(Math.floor(lines.length / 2)).join('\n')}\n`, 'utf8');

package/dist-cjs/tracing/tracer.js

@@ -4,8 +4,8 @@ exports.Tracer = void 0;
 exports.w3cTraceId = w3cTraceId;
 exports.w3cSpanId = w3cSpanId;
 exports.stripFields = stripFields;
+const ids_js_1 = require("../utils/ids.js");
 const node_async_hooks_1 = require("node:async_hooks");
-const node_crypto_1 = require("node:crypto");
 class Tracer {
     options;
     context = new node_async_hooks_1.AsyncLocalStorage();
@@ -201,7 +201,7 @@ class Tracer {
 }
 exports.Tracer = Tracer;
 function id(prefix) {
-    return `${prefix}-${(0, node_crypto_1.randomBytes)(8).toString('hex')}`;
+    return `${prefix}-${(0, ids_js_1.randomHex)(8)}`;
 }
 function w3cTraceId(traceId) {
     if (/^[0-9a-f]{32}$/.test(traceId))

package/dist-cjs/types/config.d.ts

@@ -25,6 +25,11 @@ export interface OpenAIProviderConfig {
     apiKey: string;
     /** API base URL. Point it at an OpenAI-compatible server to use that instead. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** OpenAI organization to bill. */
     organization?: string;
     /** Headers added to every request. */
@@ -59,6 +64,11 @@ export interface AnthropicProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
     /** Name this provider registers under. */
     providerName?: string;
     /** Model-name prefixes this provider answers for. */
@@ -75,6 +85,11 @@ export interface GoogleProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 /** Configuration for a local Ollama server. */
 export interface OllamaProviderConfig {
@@ -101,6 +116,11 @@ export interface CohereProviderConfig {
     apiKey: string;
     /** API base URL. */
     baseUrl?: string;
+    /**
+     * Replaces the global `fetch` for every request: a platform's bound fetch on an edge runtime, a
+     * proxy, or a stub in tests.
+     */
+    fetch?: typeof globalThis.fetch;
 }
 export interface OpenRouterProviderConfig {
     apiKey: string;

package/dist-cjs/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-cjs/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-cjs/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-cjs/types/principal.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/types/server.d.ts

@@ -6,15 +6,9 @@
  * 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';
+import type { RunFeedback } from './tracing.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. */
@@ -82,6 +76,11 @@ export interface RunRecord {
     worker?: string;
     /** Its latest attempt, starting at 1. */
     attempt?: number;
+    /**
+     * Scores left on the run by people or by online evaluation, through `POST /runs/:runId/feedback`
+     * or `Deployments.evaluate()`. A canary guard compares them between revisions as its quality signal.
+     */
+    feedback?: RunFeedback[];
 }
 /** Why a run got the revision it did. */
 export type RevisionReason = 'split' | 'thread' | 'requested';

package/dist-cjs/utils/base64.d.ts

@@ -0,0 +1,4 @@
+/** Base64 text as bytes, in a buffer of their own, so typed-array views of it are aligned. */
+export declare function decodeBase64(data: string): Uint8Array;
+/** Bytes as base64 text. */
+export declare function encodeBase64(bytes: Uint8Array): string;

package/dist-cjs/utils/base64.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeBase64 = decodeBase64;
+exports.encodeBase64 = encodeBase64;
+const host = () => globalThis.Buffer;
+function decodeBase64(data) {
+    const buffer = host();
+    if (buffer)
+        return new Uint8Array(buffer.from(data, 'base64'));
+    const binary = atob(data);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1)
+        bytes[index] = binary.charCodeAt(index);
+    return bytes;
+}
+function encodeBase64(bytes) {
+    const buffer = host();
+    if (buffer)
+        return buffer.from(bytes).toString('base64');
+    let binary = '';
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
+}

package/dist-cjs/utils/checksums.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Checks that tell a real identifier from a number that only looks like one. Every detector of card
+ * numbers and account numbers uses them, so an order id or a millisecond timestamp is never masked as
+ * a card.
+ */
+/** Whether a card number passes the Luhn check, with 13 to 19 digits; spaces and dashes are ignored. */
+export declare function luhn(value: string): boolean;
+/** Whether an IBAN passes its mod-97 check, with 15 to 34 characters; spaces are ignored. */
+export declare function ibanChecksum(value: string): boolean;
+/** Whether a phone-like match has as many digits as a phone number can: 10 to 15. */
+export declare function phoneDigits(value: string): boolean;
+/**
+ * Whether a match reads as a phone number: 10 to 15 digits, written with a leading `+` or with
+ * separators. A bare run of digits is an id or a timestamp far more often than a phone number.
+ */
+export declare function phoneNumber(value: string): boolean;
+/**
+ * Text as a detector should read it: Unicode compatibility forms folded (full-width letters become
+ * ASCII), and the invisible characters an attacker uses to split a phrase removed, so
+ * `ｉｇｎｏｒｅ` and `ig​nore` read as `ignore`.
+ */
+export declare function normalizeForDetection(text: string): string;

package/dist-cjs/utils/checksums.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.luhn = luhn;
+exports.ibanChecksum = ibanChecksum;
+exports.phoneDigits = phoneDigits;
+exports.phoneNumber = phoneNumber;
+exports.normalizeForDetection = normalizeForDetection;
+function luhn(value) {
+    const digits = value.replace(/[\s-]/g, '');
+    if (!/^\d{13,19}$/.test(digits))
+        return false;
+    let sum = 0;
+    for (let index = 0; index < digits.length; index += 1) {
+        let digit = Number(digits[digits.length - 1 - index]);
+        if (index % 2 === 1) {
+            digit *= 2;
+            if (digit > 9)
+                digit -= 9;
+        }
+        sum += digit;
+    }
+    return sum % 10 === 0;
+}
+function ibanChecksum(value) {
+    const iban = value.replace(/ /g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{11,30}$/.test(iban))
+        return false;
+    const rearranged = `${iban.slice(4)}${iban.slice(0, 4)}`;
+    let remainder = 0;
+    for (const char of rearranged) {
+        const code = /\d/.test(char) ? char : String(char.charCodeAt(0) - 55);
+        for (const digit of code)
+            remainder = (remainder * 10 + Number(digit)) % 97;
+    }
+    return remainder === 1;
+}
+function phoneDigits(value) {
+    const digits = value.replace(/\D/g, '').length;
+    return digits >= 10 && digits <= 15;
+}
+function phoneNumber(value) {
+    return phoneDigits(value) && (/^\s*\+/.test(value) || /\d[\s.()-]+\d/.test(value));
+}
+function normalizeForDetection(text) {
+    return text.normalize('NFKC').replace(/[­᠎​-‏‪-‮⁠-⁤]/g, '');
+}

package/dist-cjs/utils/ids.d.ts

@@ -1 +1,9 @@
+/**
+ * Ids and text measures from Web Crypto and plain JavaScript, so the modules that use them run on
+ * every runtime: Node.js, Deno, Bun, edge runtimes, and browsers.
+ */
+/** Random bytes as lowercase hex, two characters per byte. */
+export declare function randomHex(bytes: number): string;
 export declare function generateRequestId(): string;
+/** The bytes UTF-8 takes for a string, as `Buffer.byteLength()` counts them, without encoding it. */
+export declare function utf8Length(text: string): number;

package/dist-cjs/utils/ids.js

@@ -1,7 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.randomHex = randomHex;
 exports.generateRequestId = generateRequestId;
-const node_crypto_1 = require("node:crypto");
+exports.utf8Length = utf8Length;
+function randomHex(bytes) {
+    const values = globalThis.crypto.getRandomValues(new Uint8Array(bytes));
+    let hex = '';
+    for (const value of values)
+        hex += HEX[value];
+    return hex;
+}
 function generateRequestId() {
-    return `req_${(0, node_crypto_1.randomBytes)(12).toString('hex')}`;
+    return `req_${randomHex(12)}`;
+}
+function utf8Length(text) {
+    let length = 0;
+    for (let index = 0; index < text.length; index += 1) {
+        const code = text.charCodeAt(index);
+        if (code < 0x80)
+            length += 1;
+        else if (code < 0x800)
+            length += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && (text.charCodeAt(index + 1) & 0xfc00) === 0xdc00) {
+            length += 4;
+            index += 1;
+        }
+        else
+            length += 3;
+    }
+    return length;
 }
+const HEX = Array.from({ length: 256 }, (_, value) => value.toString(16).padStart(2, '0'));

package/dist-cjs/utils/sha256.d.ts

@@ -0,0 +1,22 @@
+/**
+ * SHA-256 that can be fed in pieces, as `createHash('sha256')` is, with the same digest. Strings are
+ * hashed as UTF-8. Synchronous, unlike Web Crypto's `digest()`, so a cache key can be computed where
+ * it is needed.
+ */
+export declare class Sha256 {
+    private readonly state;
+    private readonly block;
+    private readonly words;
+    private filled;
+    private total;
+    /** Adds data: a string, as UTF-8, or bytes. */
+    update(data: string | Uint8Array): this;
+    /** The digest as lowercase hex. The hash takes no more data afterwards. */
+    digest(): string;
+    private compress;
+}
+/**
+ * The SHA-256 digest of a string, as UTF-8, or of bytes, as lowercase hex. Native where the runtime
+ * has it, which is ten times faster on large inputs, and the same digest everywhere else.
+ */
+export declare function sha256Hex(data: string | Uint8Array): string;