nexus-ai-pro 2.0.0 → 2.2.0

package/dist-cjs/tracing/stores.js

@@ -4,6 +4,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 promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const query_js_1 = require("./query.js");
@@ -52,6 +53,29 @@ class MemoryTraceStore {
     }
 }
 exports.MemoryTraceStore = MemoryTraceStore;
+async function closeAbandonedRuns(store, options) {
+    const now = options.now?.() ?? new Date();
+    const until = new Date(now.getTime() - options.olderThanMs).toISOString();
+    let closed = 0;
+    const seen = new Set();
+    for (;;) {
+        const stuck = (await store.query({ status: 'running', until, limit: 500 })).filter((run) => !seen.has(run.id));
+        if (stuck.length === 0)
+            return closed;
+        for (const run of stuck) {
+            seen.add(run.id);
+            await store.save({
+                ...run,
+                status: 'error',
+                endedAt: now.toISOString(),
+                latencyMs: Math.max(0, now.getTime() - Date.parse(run.startedAt)),
+                error: { name: 'RunAbandoned', message: 'The process running this ended before it finished' },
+                metadata: { ...run.metadata, abandoned: true },
+            });
+            closed += 1;
+        }
+    }
+}
 class JsonlTraceStore {
     file;
     maxBytes;

package/dist-cjs/tracing/tracer.d.ts

@@ -1,16 +1,32 @@
-import type { RunFeedback, RunKind, RedactionPolicy, SamplingPolicy, TraceStore } from '../types/tracing.js';
+import type { RunFeedback, RunKind, RedactionPolicy, SamplingPolicy, TraceExporter, TraceStore } from '../types/tracing.js';
 /** Configuration for a tracer. */
 export interface TracerOptions {
-    /** Where finished traces are written. */
+    /** Where runs are written. */
     store: TraceStore;
     /** Which traces are kept. */
     sampling?: SamplingPolicy;
-    /** What is removed from runs before they are stored. */
+    /** What is removed from runs before they are stored or exported. */
     redaction?: RedactionPolicy;
     /** Tags added to every run, such as the deployment or the release. */
     tags?: string[];
     /** Metadata added to every run. */
     metadata?: Record<string, unknown>;
+    /**
+     * Writes each run when it starts and again when it ends, instead of a whole trace once its root
+     * finishes.
+     *
+     * A trace written at the end is lost with the process that held it. Written as it runs, a crashed
+     * run stays in the store with every run that finished, and a run in progress can be watched.
+     * Sampling is then decided when the root starts. A trace not sampled is still held in memory and
+     * written at the end when tail sampling keeps it, so `keepErrors` still shows every failure.
+     * Defaults to false, which writes at the end, as before.
+     */
+    incremental?: boolean;
+    /**
+     * Also hands every finished run that is kept to these exporters, after redaction, such as an
+     * `OtlpTraceExporter` sending OpenTelemetry spans to a collector.
+     */
+    exporters?: TraceExporter[];
     /** Replaces the system clock, for tests. */
     now?: () => Date;
     /** Errors from the store are swallowed by default; a hook lets an application notice them. */
@@ -36,6 +52,12 @@ export interface StartRunOptions {
     parentId?: string;
     /** Joins an existing trace instead of starting a new one. */
     traceId?: string;
+    /**
+     * Continues a trace another process started, from a W3C `traceparent` header such as the one
+     * `RunHandle.traceparent()` returns or an OpenTelemetry service sends. The run joins that trace,
+     * under the span the header names, and keeps its sampling decision.
+     */
+    traceparent?: string;
 }
 /** Options for finishing a run. */
 export interface FinishRunOptions {
@@ -60,10 +82,19 @@ export interface RunHandle {
     readonly id: string;
     /** The trace it belongs to. */
     readonly traceId: string;
-    /** Finishes the run. The trace is written once its root finishes. */
+    /**
+     * Finishes the run. By default the trace is written once its root finishes; with `incremental`,
+     * this run is written now.
+     */
     finish(options?: FinishRunOptions): Promise<void>;
     /** Starts a run beneath this one, without relying on the ambient context. */
     child(options: StartRunOptions): RunHandle;
+    /**
+     * This run as a W3C `traceparent` header, for work it hands to another process: an operation's
+     * `traceContext`, a request to a remote graph, a call to any OpenTelemetry service. Pass it back
+     * as `StartRunOptions.traceparent` there.
+     */
+    traceparent(): string;
 }
 /**
  * Records run trees.
@@ -75,6 +106,8 @@ export declare class Tracer {
     private readonly options;
     private readonly context;
     private readonly pending;
+    /** Each trace's writes, in order, so a run's end can never land before its start. */
+    private readonly writes;
     private readonly now;
     constructor(options: TracerOptions);
     /** The run currently in scope, if any. */
@@ -95,12 +128,25 @@ export declare class Tracer {
     recordFeedback(runId: string, feedback: Omit<RunFeedback, 'createdAt'> & {
         createdAt?: string;
     }): Promise<void>;
+    /** Waits for every write and export handed over so far. */
+    flush(): Promise<void>;
     private handle;
     private close;
+    /** Chains a write behind the trace's earlier ones. A failed write is reported, never thrown. */
+    private enqueue;
+    private settle;
+    private export;
     private keepByTail;
     private decideSampling;
     /** Applies the redaction policy. What a trace must not hold, it never holds. */
     private prepare;
 }
+/**
+ * A trace id as the 32 hex digits W3C trace context and OpenTelemetry use. An id that already is one
+ * is kept; a tracer's own `trace-…` id is padded, so every process derives the same one.
+ */
+export declare function w3cTraceId(traceId: string): string;
+/** A run id as the 16 hex digits of a W3C span id. */
+export declare function w3cSpanId(runId: string): string;
 /** Removes fields by dot path, deeply, without mutating what the caller passed in. */
 export declare function stripFields(value: unknown, fields: readonly string[]): unknown;

package/dist-cjs/tracing/tracer.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Tracer = void 0;
+exports.w3cTraceId = w3cTraceId;
+exports.w3cSpanId = w3cSpanId;
 exports.stripFields = stripFields;
 const node_async_hooks_1 = require("node:async_hooks");
 const node_crypto_1 = require("node:crypto");
@@ -8,6 +10,7 @@ class Tracer {
     options;
     context = new node_async_hooks_1.AsyncLocalStorage();
     pending = new Map();
+    writes = new Map();
     now;
     constructor(options) {
         this.options = options;
@@ -19,13 +22,15 @@ class Tracer {
     }
     startRun(options) {
         const parent = this.context.getStore();
-        const traceId = options.traceId ?? parent?.traceId ?? id('trace');
+        const remote = options.traceparent ? parseTraceparent(options.traceparent) : undefined;
+        const traceId = options.traceId ?? remote?.traceId ?? parent?.traceId ?? id('trace');
         const runId = id('run');
-        const sampled = parent?.sampled ?? this.decideSampling();
+        const parentId = options.parentId ?? (remote ? `run-${remote.spanId}` : parent?.runId);
+        const sampled = parent?.sampled ?? remote?.sampled ?? this.decideSampling();
         const run = {
             id: runId,
             traceId,
-            ...((options.parentId ?? parent?.runId) ? { parentId: options.parentId ?? parent?.runId } : {}),
+            ...(parentId ? { parentId } : {}),
             name: options.name,
             kind: options.kind ?? 'chain',
             status: 'running',
@@ -36,7 +41,12 @@ class Tracer {
             tags: [...(this.options.tags ?? []), ...(options.tags ?? [])],
             metadata: { ...this.options.metadata, ...options.metadata },
         };
-        this.pending.set(traceId, [...(this.pending.get(traceId) ?? []), run]);
+        if (this.options.incremental && sampled) {
+            this.enqueue(run.traceId, () => this.options.store.save(this.prepare(run)));
+        }
+        else {
+            this.pending.set(traceId, [...(this.pending.get(traceId) ?? []), run]);
+        }
         return this.handle(run, sampled);
     }
     async trace(options, fn) {
@@ -70,6 +80,10 @@ class Tracer {
             this.options.onError?.(error);
         }
     }
+    async flush() {
+        await Promise.all([...this.writes.values()]);
+        await Promise.all((this.options.exporters ?? []).map((exporter) => Promise.resolve(exporter.flush?.()).catch((error) => this.options.onError?.(error))));
+    }
     handle(run, sampled) {
         const finish = async (options = {}) => {
             const endedAt = this.now();
@@ -86,6 +100,16 @@ class Tracer {
                 ...(options.provider ? { provider: options.provider } : {}),
                 metadata: { ...run.metadata, ...options.metadata },
             };
+            if (this.options.incremental && sampled) {
+                await this.enqueue(run.traceId, async () => {
+                    const prepared = this.prepare(finished);
+                    await this.options.store.save(prepared);
+                    this.export(prepared);
+                });
+                if (!run.parentId)
+                    this.settle(run.traceId);
+                return;
+            }
             await this.close(finished, sampled);
         };
         return {
@@ -93,6 +117,7 @@ class Tracer {
             traceId: run.traceId,
             finish,
             child: (options) => this.startRun({ ...options, traceId: run.traceId, parentId: run.id }),
+            traceparent: () => formatTraceparent(run.traceId, run.id, sampled),
         };
     }
     async close(run, sampled) {
@@ -102,7 +127,7 @@ class Tracer {
             runs[index] = run;
         else
             runs.push(run);
-        const root = runs.find((item) => !item.parentId);
+        const root = runs.find((item) => !item.parentId || !runs.some((other) => other.id === item.parentId));
         if (root && root.status === 'running')
             return;
         this.pending.delete(run.traceId);
@@ -110,7 +135,34 @@ class Tracer {
             return;
         for (const item of runs) {
             try {
-                await this.options.store.save(this.prepare(item));
+                const prepared = this.prepare(item);
+                await this.options.store.save(prepared);
+                if (prepared.status !== 'running')
+                    this.export(prepared);
+            }
+            catch (error) {
+                this.options.onError?.(error);
+            }
+        }
+    }
+    enqueue(traceId, write) {
+        const next = (this.writes.get(traceId) ?? Promise.resolve())
+            .then(write)
+            .catch((error) => this.options.onError?.(error));
+        this.writes.set(traceId, next);
+        return next;
+    }
+    settle(traceId) {
+        const last = this.writes.get(traceId);
+        void last?.then(() => {
+            if (this.writes.get(traceId) === last)
+                this.writes.delete(traceId);
+        });
+    }
+    export(run) {
+        for (const exporter of this.options.exporters ?? []) {
+            try {
+                void Promise.resolve(exporter.export(run)).catch((error) => this.options.onError?.(error));
             }
             catch (error) {
                 this.options.onError?.(error);
@@ -151,6 +203,35 @@ exports.Tracer = Tracer;
 function id(prefix) {
     return `${prefix}-${(0, node_crypto_1.randomBytes)(8).toString('hex')}`;
 }
+function w3cTraceId(traceId) {
+    if (/^[0-9a-f]{32}$/.test(traceId))
+        return traceId;
+    const hex = traceId
+        .replace(/^trace-/, '')
+        .replace(/[^0-9a-f]/gi, '')
+        .toLowerCase();
+    return hex.length >= 32 ? hex.slice(-32) : hex.padStart(32, '0');
+}
+function w3cSpanId(runId) {
+    const hex = runId
+        .replace(/^run-/, '')
+        .replace(/[^0-9a-f]/gi, '')
+        .toLowerCase();
+    return hex.length >= 16 ? hex.slice(-16) : hex.padStart(16, '0');
+}
+function formatTraceparent(traceId, runId, sampled) {
+    return `00-${w3cTraceId(traceId)}-${w3cSpanId(runId)}-${sampled ? '01' : '00'}`;
+}
+function parseTraceparent(header) {
+    const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(header.trim().toLowerCase());
+    if (!match || match[2] === '0'.repeat(32) || match[3] === '0'.repeat(16))
+        return undefined;
+    return {
+        traceId: match[2],
+        spanId: match[3],
+        sampled: (Number.parseInt(match[4], 16) & 1) === 1,
+    };
+}
 function describeError(error) {
     if (error instanceof Error)
         return { name: error.name, message: error.message };

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

@@ -8,6 +8,7 @@ import type { TelephonyConfig } from './telephony.js';
 import type { AliasMetadata, InputModality, ModelCapabilities, ModelStatus, OutputModality, RoutingModelPreference } from './providers.js';
 import type { CapabilityConfig } from './capabilities.js';
 import type { LifecycleConfig, OperationFamily } from './lifecycle.js';
+import type { CompletionRequest } from './messages.js';
 import type { PipelineConfig } from '../pipeline/types.js';
 import type { CacheAdapter } from '../cache/adapters.js';
 import type { SemanticCacheOptions } from '../cache/semantic-cache.js';
@@ -228,6 +229,24 @@ export interface CacheConfig {
     strategy?: 'exact' | 'semantic' | 'hybrid';
     adapter?: CacheAdapter;
     semantic?: SemanticCacheOptions;
+    /**
+     * What cached responses are kept apart by, fixed or per request. A response is reused only within
+     * its namespace, so a new model revision or context version starts from an empty cache, and no
+     * tenant is answered from another's. The tenant defaults to the request's `tenantId`. Without it,
+     * exact-cache keys are what they were before 2.2; semantic matches are always kept to one tenant.
+     */
+    namespace?: CacheNamespace | ((request: CompletionRequest) => CacheNamespace);
+}
+/** What a cached response is kept apart by. Each field narrows the namespace. */
+export interface CacheNamespace {
+    /** The tenant. Defaults to the request's `tenantId`. */
+    tenant?: string;
+    /** The deployment environment, such as `staging`. */
+    environment?: string;
+    /** A revision of the model or its prompts; changing it retires every earlier entry. */
+    modelRevision?: string;
+    /** The version of the context an answer depends on, such as a context hub bundle's. */
+    contextVersion?: string;
 }
 /** A response format applied to every request that does not set its own. */
 export interface ResponseFormatConfig {
@@ -244,8 +263,20 @@ export interface RateLimitConfig {
     maxRequests: number;
     /** Window length in milliseconds. */
     windowMs: number;
-    /** What a budget is counted per: each user, each model, or everything together. */
-    key?: 'userId' | 'model' | 'global';
+    /**
+     * What a budget is counted per: each user, each model, each tenant (the request's `tenantId`), or
+     * everything together. Per tenant, one tenant cannot spend another's share of a shared client.
+     */
+    key?: 'userId' | 'model' | 'tenantId' | 'global';
+    /**
+     * How calls are counted. `fixed-window` (the default) counts per window, so a burst at the end of
+     * one window and another at the start of the next can pass twice the limit in a moment. `gcra` is
+     * the token-bucket algorithm kept as one timestamp per key: calls are spread at `maxRequests` per
+     * `windowMs`, with at most `burst` at once, and no window edge to burst across.
+     */
+    algorithm?: 'fixed-window' | 'gcra';
+    /** With `gcra`, the calls allowed at once after a quiet spell. Defaults to `maxRequests`. */
+    burst?: number;
     /**
      * Where counters live. Omitted means process-local, which multiplies the real limit by the
      * number of workers; supply `RedisRateLimitStore` to share one budget across them.

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

@@ -166,6 +166,43 @@ export interface Experiment {
         hits: number;
         misses: number;
     };
+    /** Where each evaluator's scores came from, in the order the evaluators were given. */
+    evaluators?: EvaluatorProvenance[];
+    /** The framework that ran the experiment. */
+    framework?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Where one evaluator's scores came from. `position`, `name`, and `keys` are always recorded; the
+ * rest is what the evaluator declared through `withProvenance()`, or what an `LLMJudge` declares for
+ * itself.
+ */
+export interface EvaluatorProvenance {
+    /** Its place among the evaluators passed to `evaluate()`, from 0. */
+    position: number;
+    /** What it is called: as declared, its function's name, or `evaluator-<position>`. */
+    name: string;
+    /** The score keys it produced in this experiment. */
+    keys: string[];
+    /** Its version, as declared. */
+    version?: string;
+    /** The model behind a judge, and how it was called. */
+    judge?: {
+        /** The judge model. */
+        model: string;
+        /** The provider, when known. */
+        provider?: string;
+        /** Identifies the judge's instructions: a version, or a hash of its prompt. */
+        promptVersion?: string;
+        /** Its sampling temperature. */
+        temperature?: number;
+    };
+    /** What a good answer looks like, as the evaluator was told. */
+    rubric?: string;
+    /** Anything else worth recording. */
+    metadata?: Record<string, unknown>;
 }
 /** Where experiments are kept, for later comparison. */
 export interface ExperimentStore {