nexus-ai-pro 2.2.0 → 2.3.0

package/dist-cjs/rag/rerankers.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RerankerError = void 0;
+exports.httpReranker = httpReranker;
+exports.cohereReranker = cohereReranker;
+exports.voyageReranker = voyageReranker;
+exports.jinaReranker = jinaReranker;
+exports.teiReranker = teiReranker;
+exports.crossEncoderReranker = crossEncoderReranker;
+const signals_js_1 = require("../utils/signals.js");
+class RerankerError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'RerankerError';
+    }
+}
+exports.RerankerError = RerankerError;
+function httpReranker(options) {
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const limit = options.maxChunkCharacters ?? 4_000;
+    return async (query, chunks, signal) => {
+        if (chunks.length === 0)
+            return [];
+        const passages = chunks.map((chunk) => chunk.content.slice(0, limit));
+        const linked = (0, signals_js_1.linkSignals)([AbortSignal.timeout(options.timeoutMs ?? 30_000), signal]);
+        try {
+            const response = await fetchImpl(options.url, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json', ...options.headers },
+                body: JSON.stringify(options.body(query, passages)),
+                signal: linked.signal,
+            });
+            const text = await response.text();
+            if (!response.ok)
+                throw new RerankerError(`The rerank API answered ${response.status}`, response.status, text);
+            const scores = new Array(chunks.length).fill(0);
+            for (const { index, score } of options.scores(JSON.parse(text))) {
+                if (Number.isInteger(index) && index >= 0 && index < scores.length)
+                    scores[index] = Number(score);
+            }
+            return scores;
+        }
+        finally {
+            linked.dispose();
+        }
+    };
+}
+const bearer = (options) => ({ authorization: `Bearer ${options.apiKey}`, ...options.headers });
+const readScored = (list) => (list ?? []).map((item) => ({ index: item.index, score: item.relevance_score }));
+function cohereReranker(options) {
+    return httpReranker({
+        ...options,
+        url: options.url ?? 'https://api.cohere.com/v2/rerank',
+        headers: bearer(options),
+        body: (query, documents) => ({ model: options.model, query, documents, top_n: documents.length }),
+        scores: (response) => readScored(response.results),
+    });
+}
+function voyageReranker(options) {
+    return httpReranker({
+        ...options,
+        url: options.url ?? 'https://api.voyageai.com/v1/rerank',
+        headers: bearer(options),
+        body: (query, documents) => ({ model: options.model, query, documents, top_k: documents.length }),
+        scores: (response) => readScored(response.data),
+    });
+}
+function jinaReranker(options) {
+    return httpReranker({
+        ...options,
+        url: options.url ?? 'https://api.jina.ai/v1/rerank',
+        headers: bearer(options),
+        body: (query, documents) => ({ model: options.model, query, documents, top_n: documents.length }),
+        scores: (response) => readScored(response.results),
+    });
+}
+function teiReranker(options) {
+    return httpReranker({
+        ...options,
+        url: `${options.url.replace(/\/+$/, '')}/rerank`,
+        body: (query, texts) => ({ query, texts, raw_scores: false, truncate: true }),
+        scores: (response) => response,
+    });
+}
+function crossEncoderReranker(model, options = {}) {
+    const batchSize = Math.max(1, options.batchSize ?? 32);
+    const limit = options.maxChunkCharacters ?? 2_000;
+    return async (query, chunks, signal) => {
+        const pairs = chunks.map((chunk) => [query, chunk.content.slice(0, limit)]);
+        const scores = [];
+        for (let start = 0; start < pairs.length; start += batchSize) {
+            signal?.throwIfAborted();
+            const batch = pairs.slice(start, start + batchSize);
+            const result = await model.score(batch);
+            if (result.length !== batch.length) {
+                throw new RangeError(`The cross-encoder returned ${result.length} scores for ${batch.length} pairs`);
+            }
+            for (const raw of result)
+                scores.push(options.sigmoid ? 1 / (1 + Math.exp(-raw)) : raw);
+        }
+        return scores;
+    };
+}

package/dist-cjs/rag/retrievers.d.ts

@@ -19,6 +19,17 @@ export interface Retriever {
     /** The chunks that best answer a query, best first. */
     retrieve(query: string, options?: RetrieveOptions): Promise<VectorSearchResult[]>;
 }
+/**
+ * Keyword search that holds its own chunks: an in-memory BM25 `KeywordIndex`, Postgres full-text
+ * search, a search engine. It is a `Retriever`, so `hybridRetriever()` fuses it with vector search,
+ * and it takes writes, so ingestion keeps it in step with a vector store.
+ */
+export interface SparseRetriever extends Retriever {
+    /** Adds chunks, or replaces those whose id exists. */
+    add(chunks: readonly RagChunk[]): Promise<void> | void;
+    /** Removes chunks by id. An id that is not held is ignored. */
+    delete(ids: readonly string[]): Promise<void> | void;
+}
 /** A client that runs one completion — a `NexusAI` instance, or anything with the same `complete()`. */
 export interface RetrievalModelClient {
     /** Runs one completion and returns its text. */
@@ -47,7 +58,7 @@ export declare function tokenize(text: string): string[];
  * codes, error numbers, names — that keyword search finds; `hybridRetriever()` fuses the two.
  * Adding a chunk whose id exists replaces it, as in a vector store.
  */
-export declare class KeywordIndex implements Retriever {
+export declare class KeywordIndex implements SparseRetriever {
     private readonly chunks;
     private readonly postings;
     private totalLength;

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

@@ -1,5 +1,5 @@
 import type { GraphStreamProjection } from '../types/graph.js';
-import type { AssistantRunContext, ServerAssistant } from '../types/server.js';
+import type { AssistantRunContext, Principal, ServerAssistant } from '../types/server.js';
 /**
  * The part of a compiled graph the adapter uses.
  *
@@ -13,6 +13,7 @@ export interface GraphLike {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
         tenantId?: string;
+        principal?: Principal;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Answers an interrupt and continues the thread. */
@@ -20,6 +21,7 @@ export interface GraphLike {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
         tenantId?: string;
+        principal?: Principal;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** The thread's checkpoint, at its latest step or at one given. */
@@ -34,6 +36,7 @@ export interface GraphLike {
         signal?: AbortSignal;
         metadata?: Record<string, unknown>;
         tenantId?: string;
+        principal?: Principal;
         control?: DrainSwitch;
     }): AsyncIterable<unknown>;
     /** Writes values into a thread's state, which is how a rollback is applied. */
@@ -51,6 +54,7 @@ export interface GraphLike {
 type GraphEventOptionsLike = {
     threadId?: string;
     tenantId?: string;
+    principal?: Principal;
     signal?: AbortSignal;
     metadata?: Record<string, unknown>;
     control?: DrainSwitch;

package/dist-cjs/server/assistant.js

@@ -85,8 +85,10 @@ function functionAssistant(run, options = {}) {
     };
 }
 function tenantOf(context) {
-    const tenantId = context.principal?.tenantId;
-    return tenantId ? { tenantId } : {};
+    const principal = context.principal;
+    if (!principal)
+        return {};
+    return { ...(principal.tenantId ? { tenantId: principal.tenantId } : {}), principal };
 }
 async function* withResult(events) {
     for await (const event of events)

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

@@ -0,0 +1,250 @@
+/**
+ * Authentication for the agent server: JSON Web Tokens, API keys, and a trusted proxy.
+ *
+ * Each builds the `authenticate` hook of `createAgentServer()`, and each returns the same
+ * `Principal`: a subject, a tenant, roles, and scopes. That principal is what scopes threads, runs,
+ * budgets, and the store to a tenant, and what reaches every graph node, tool, and middleware of the
+ * run. Everything is built on Web Crypto, so there is no dependency and it runs wherever `fetch` does.
+ */
+import type { webcrypto } from 'node:crypto';
+import type { Principal } from '../types/principal.js';
+type JsonWebKey = webcrypto.JsonWebKey;
+type CryptoKey = webcrypto.CryptoKey;
+/** The `authenticate` hook of `createAgentServer()`. */
+export type AuthHook = (request: Request) => Promise<Principal | Response | undefined> | Principal | Response | undefined;
+/** The signature algorithms a token may use. `none` is never accepted. */
+export type JwtAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512' | 'EdDSA';
+/** A token's claims, the registered ones typed. */
+export interface JwtPayload {
+    /** The issuer. */
+    iss?: string;
+    /** The subject: who the token is about. */
+    sub?: string;
+    /** The audience: who the token is for. */
+    aud?: string | string[];
+    /** Expiry, in seconds since the epoch. */
+    exp?: number;
+    /** Not valid before, in seconds since the epoch. */
+    nbf?: number;
+    /** Issued at, in seconds since the epoch. */
+    iat?: number;
+    /** The token's id. */
+    jti?: string;
+    /** Every other claim. */
+    [claim: string]: unknown;
+}
+/** A token's header. */
+export interface JwtHeader {
+    /** The signature algorithm. */
+    alg: string;
+    /** The id of the key that signed it, for choosing one from a key set. */
+    kid?: string;
+    /** The token type, usually `JWT`. */
+    typ?: string;
+    /** Any other header field. */
+    [field: string]: unknown;
+}
+/** A verified token. */
+export interface VerifiedJwt {
+    /** Its header. */
+    header: JwtHeader;
+    /** Its claims, each checked. */
+    payload: JwtPayload;
+}
+/** Why a token was refused. */
+export type JwtErrorCode = 'JWT_MALFORMED' | 'JWT_ALGORITHM' | 'JWT_KEY' | 'JWT_SIGNATURE' | 'JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_TOO_OLD' | 'JWT_ISSUER' | 'JWT_AUDIENCE' | 'JWT_CLAIM';
+/** Thrown when a token is refused: malformed, signed wrongly, expired, or for someone else. */
+export declare class JwtError extends Error {
+    /** Why. */
+    readonly code: JwtErrorCode;
+    constructor(
+    /** Why. */
+    code: JwtErrorCode, message: string);
+}
+/** Options for `createJwtVerifier()`. Give it one key source: `secret`, `publicKey`, or `jwks`. */
+export interface JwtVerifyOptions {
+    /** A shared secret, for HS256, HS384, and HS512. */
+    secret?: string | Uint8Array;
+    /** One public key: PEM (`-----BEGIN PUBLIC KEY-----`), a JWK, or a `CryptoKey`. */
+    publicKey?: string | JsonWebKey | CryptoKey;
+    /**
+     * The identity provider's key set: its URL, or the keys themselves. Fetched keys are cached, and
+     * a token naming a key not yet seen fetches the set again, so a provider's key rotation needs no
+     * restart.
+     */
+    jwks?: string | URL | {
+        keys: JsonWebKey[];
+    };
+    /**
+     * The algorithms accepted. Defaults to HS256, HS384, and HS512 for a secret and to every
+     * asymmetric algorithm for a public key or a key set. A shared secret is never accepted for an
+     * asymmetric algorithm, nor a public key for HMAC, so one cannot be passed off as the other.
+     */
+    algorithms?: readonly JwtAlgorithm[];
+    /** The issuer a token must name: one, or any of several. */
+    issuer?: string | readonly string[];
+    /**
+     * The audience a token must be for: one, or any of several. Required with `jwks`, where a
+     * provider signs tokens for every application it serves; `false` accepts any audience,
+     * deliberately.
+     */
+    audience?: string | readonly string[] | false;
+    /** Seconds of clock difference tolerated on `exp`, `nbf`, and `iat`. Defaults to 60. */
+    clockToleranceSec?: number;
+    /** The oldest a token may be, from its `iat`, in seconds. */
+    maxAgeSec?: number;
+    /** Requires an `exp` claim. Defaults to true: a token that never expires is refused. */
+    requireExpiry?: boolean;
+    /** Claims a token must carry, besides `exp`. */
+    requiredClaims?: readonly string[];
+    /** How long a fetched key set is kept, in milliseconds. Defaults to 10 minutes. */
+    jwksCacheMs?: number;
+    /**
+     * The least time between two fetches for keys not yet seen, in milliseconds, so tokens naming keys
+     * that do not exist cannot make the server hammer the provider. Defaults to 30 seconds.
+     */
+    jwksCooldownMs?: number;
+    /** Fetches the key set. Defaults to the global `fetch`. */
+    fetch?: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    /** Replaces the clock, in milliseconds since the epoch, for tests. */
+    now?: () => number;
+}
+/** A reusable verifier: it keeps imported keys and the fetched key set between tokens. */
+export interface JwtVerifier {
+    /** Verifies a token: its form, its signature, and its claims. Throws `JwtError` when it is refused. */
+    verify(token: string): Promise<VerifiedJwt>;
+}
+/**
+ * Builds a verifier for tokens from one issuer.
+ *
+ * ```ts
+ * const verifier = createJwtVerifier({
+ *   jwks: 'https://login.example.com/.well-known/jwks.json',
+ *   issuer: 'https://login.example.com/',
+ *   audience: 'agents-api',
+ * });
+ * const { payload } = await verifier.verify(token);
+ * ```
+ */
+export declare function createJwtVerifier(options: JwtVerifyOptions): JwtVerifier;
+/** Which claims a principal is read from. A dot reaches into a nested claim: `realm_access.roles`. */
+export interface JwtClaimNames {
+    /** The subject. Defaults to `sub`. */
+    subject?: string;
+    /** The tenant. Defaults to `tenant_id`. */
+    tenant?: string;
+    /** The roles, as a list or a space-separated string. Defaults to `roles`. */
+    roles?: string;
+    /** The scopes, as a space-separated string or a list. Defaults to `scope`, then `scp`. */
+    scopes?: string;
+}
+/** Options for `jwtAuth()`. */
+export interface JwtAuthOptions extends JwtVerifyOptions {
+    /** Reads the token from a request. Defaults to `Authorization: Bearer <token>`; a cookie works too. */
+    token?: (request: Request) => string | undefined;
+    /** Which claims the principal is read from. */
+    claims?: JwtClaimNames;
+    /**
+     * Builds the principal from the verified claims instead, for a mapping of your own. Returning
+     * nothing refuses the request with 403: the token is valid, but not for this server.
+     */
+    principal?: (payload: JwtPayload, request: Request) => Principal | undefined | Promise<Principal | undefined>;
+}
+/**
+ * Authenticates requests by a JSON Web Token: an identity provider's, through its key set, or your
+ * own, signed with a shared secret.
+ *
+ * A request with no token is passed over, so another hook in `anyAuth()` can try. A token that is
+ * refused answers 401 with a `WWW-Authenticate` challenge naming why, and a valid one becomes a
+ * `Principal`: its subject, tenant, roles, and scopes, with `method: 'jwt'` and the verified claims.
+ *
+ * ```ts
+ * createAgentServer({
+ *   assistants,
+ *   authenticate: jwtAuth({
+ *     jwks: 'https://login.example.com/.well-known/jwks.json',
+ *     issuer: 'https://login.example.com/',
+ *     audience: 'agents-api',
+ *     claims: { tenant: 'org_id', roles: 'realm_access.roles' },
+ *   }),
+ * });
+ * ```
+ */
+export declare function jwtAuth(options: JwtAuthOptions): AuthHook;
+/** Options for `apiKeyAuth()`. Give it `keys`, `lookup`, or both. */
+export interface ApiKeyAuthOptions {
+    /**
+     * Keys by their SHA-256 hash, from `hashApiKey()`, each with the principal it stands for. The keys
+     * themselves are never written into configuration.
+     */
+    keys?: Readonly<Record<string, Principal>>;
+    /** Looks a key up by its hash, in a database or a secret store, when `keys` does not have it. */
+    lookup?: (hash: string, request: Request) => Principal | undefined | Promise<Principal | undefined>;
+    /** The header the key is read from. Defaults to `x-api-key`, then `Authorization: Bearer`. */
+    header?: string;
+    /**
+     * Only a credential with this prefix is taken for a key, such as `nxk_`, so a token in the same
+     * header is left to another hook. Without it, anything shaped like a JWT is left alone.
+     */
+    prefix?: string;
+}
+/** The SHA-256 of an API key, as hex: what `apiKeyAuth({ keys })` is configured with. */
+export declare function hashApiKey(key: string): Promise<string>;
+/**
+ * Authenticates requests by an API key, for services and scripts rather than people.
+ *
+ * Keys are compared by their hash, so configuration and the database hold hashes only. A request
+ * with no key is passed over; an unknown key answers 401. The principal is the one the key maps to,
+ * with `method: 'api-key'`.
+ *
+ * ```ts
+ * apiKeyAuth({ keys: { [await hashApiKey(process.env.CI_KEY)]: { userId: 'ci', tenantId: 'acme', scopes: ['write'] } } })
+ * ```
+ */
+export declare function apiKeyAuth(options: ApiKeyAuthOptions): AuthHook;
+/** The headers a proxy names the caller in. */
+export interface TrustedProxyHeaders {
+    /** The user. Defaults to `x-forwarded-user`. */
+    user?: string;
+    /** The tenant. Defaults to `x-forwarded-tenant`. */
+    tenant?: string;
+    /** The roles. Defaults to `x-forwarded-roles`. */
+    roles?: string;
+    /** The scopes. Defaults to `x-forwarded-scopes`. */
+    scopes?: string;
+}
+/** Options for `trustedProxyAuth()`. Give it `secret`, `trust`, or both. */
+export interface TrustedProxyAuthOptions {
+    /** A header the proxy sets to a shared secret, which proves the request came through it. */
+    secret?: {
+        header: string;
+        value: string;
+    };
+    /** Decides whether a request came through the proxy, by a check of your own. */
+    trust?: (request: Request) => boolean | Promise<boolean>;
+    /** The headers the caller is named in. */
+    headers?: TrustedProxyHeaders;
+    /** What separates several roles or scopes in one header. Defaults to a comma; spaces are trimmed. */
+    separator?: string;
+}
+/**
+ * Takes the caller from headers an authenticating proxy sets: an identity-aware proxy, an API
+ * gateway, a service mesh.
+ *
+ * Headers are only as trustworthy as the path a request took, so this refuses to exist without a
+ * proof that the proxy sent the request: a shared secret it adds, a check of your own, or both. A
+ * request without that proof, or without a user, is passed over. The principal carries
+ * `method: 'proxy'`.
+ */
+export declare function trustedProxyAuth(options: TrustedProxyAuthOptions): AuthHook;
+/**
+ * Tries hooks in order and takes the first principal: tokens for people and keys for services on
+ * one server. When none accepts the request, the first refusal any of them gave is the answer, so a
+ * caller learns why their credential was refused.
+ *
+ * ```ts
+ * authenticate: anyAuth(jwtAuth({ ... }), apiKeyAuth({ ... }))
+ * ```
+ */
+export declare function anyAuth(...hooks: AuthHook[]): AuthHook;
+export {};