nexus-ai-pro 2.3.0 → 2.5.0

package/dist/context-hub/signing.d.ts

@@ -0,0 +1,95 @@
+import type { PromptDefinition } from '../types/prompts.js';
+/** A JSON Web Key, as Web Crypto exports one. */
+export interface ContextJsonWebKey {
+    /** The key type: `OKP` for Ed25519. */
+    kty?: string;
+    /** The curve: `Ed25519`. */
+    crv?: string;
+    /** The public key, in base64url. */
+    x?: string;
+    /** The private key, in base64url, on a private key only. */
+    d?: string;
+    /** Anything else the exporter wrote. */
+    [field: string]: unknown;
+}
+/** A Web Crypto key, as `crypto.subtle` returns one. Any runtime's `CryptoKey` is one. */
+export interface ContextCryptoKey {
+    /** Its algorithm. */
+    readonly algorithm: unknown;
+    /** What it may do. */
+    readonly usages: readonly string[];
+}
+/** One signature on a bundle version. Stored with it, and carried by its export. */
+export interface ContextSignature {
+    /** The id of the key that signed, which a keyring looks up. */
+    keyId: string;
+    /** Always `Ed25519`. */
+    algorithm: 'Ed25519';
+    /**
+     * What was signed: `sha256:` and the full SHA-256, in hex, of the bundle's content and the content
+     * of every prompt it pins. A bundle's version is only the first 12 hex digits, enough to name a
+     * version but not to stand behind a signature.
+     */
+    digest: string;
+    /** The signature over the digest, in base64url. */
+    signature: string;
+    /** ISO-8601 time it was signed. */
+    signedAt: string;
+}
+/** Signs bundle digests with a private key, under a key id. */
+export interface ContextSigner {
+    /** The key's id, recorded on each signature so a keyring finds the public key. */
+    keyId: string;
+    /** Signs bytes. */
+    sign(data: Uint8Array): Promise<Uint8Array> | Uint8Array;
+}
+/** Verifies signatures by key id. A signature by a key the keyring does not hold never verifies. */
+export interface ContextKeyring {
+    /** Whether `signature` is `keyId`'s signature over `data`. */
+    verify(keyId: string, data: Uint8Array, signature: Uint8Array): Promise<boolean> | boolean;
+}
+/** A new signing key, with both halves as JSON Web Keys to keep in a secret store. */
+export interface ContextSigningKey {
+    /** The key's id. */
+    keyId: string;
+    /** Signs with the new key. */
+    signer: ContextSigner;
+    /** The public half, for every keyring that should trust it. */
+    publicKey: ContextJsonWebKey;
+    /** The private half. Keep it where the signer runs, and nowhere else. */
+    privateKey: ContextJsonWebKey;
+}
+/**
+ * Creates an Ed25519 signing key through Web Crypto, so on any runtime. The key id defaults to the
+ * first 16 hex digits of the public key's SHA-256, which is stable for the key and names nothing
+ * else.
+ */
+export declare function generateContextKey(keyId?: string): Promise<ContextSigningKey>;
+/** A signer from an Ed25519 private key, as a JSON Web Key or a Web Crypto key. */
+export declare function ed25519Signer(keyId: string, privateKey: ContextJsonWebKey | ContextCryptoKey): Promise<ContextSigner>;
+/** A keyring of trusted Ed25519 public keys, by key id. */
+export declare function ed25519Keyring(keys: Record<string, ContextJsonWebKey | ContextCryptoKey>): Promise<ContextKeyring>;
+/** What a bundle signature covers: the bundle's versioned content, and its pinned prompts' content. */
+export interface ContextSignedContent {
+    /** The bundle's name and the content its version covers. */
+    bundle: {
+        name: string;
+        description?: string;
+        prompts?: Record<string, {
+            name: string;
+            version: string;
+        }>;
+        instructions?: Record<string, string>;
+        tools?: unknown;
+        skills?: unknown;
+        config?: Record<string, unknown>;
+    };
+    /** Each pinned prompt's content, by role: what its own version covers. */
+    prompts: Record<string, Pick<PromptDefinition, 'name' | 'messages' | 'partials' | 'config' | 'defaults'>>;
+}
+/** The digest a signature covers, as `sha256:` and 64 hex digits. */
+export declare function contextDigest(content: ContextSignedContent): Promise<string>;
+/** Signs a digest. */
+export declare function signDigest(signer: ContextSigner, digest: string, at: Date): Promise<ContextSignature>;
+/** The first signature that is a trusted key's signature over exactly this digest, if any. */
+export declare function verifiedBy(keyring: ContextKeyring, digest: string, signatures?: readonly ContextSignature[]): Promise<ContextSignature | undefined>;

package/dist/context-hub/signing.js

@@ -0,0 +1,88 @@
+import { canonicalJson } from '../prompts/version.js';
+import { decodeBase64, encodeBase64 } from '../utils/base64.js';
+const subtle = () => globalThis.crypto.subtle;
+const ED25519 = { name: 'Ed25519' };
+export async function generateContextKey(keyId) {
+    const pair = await subtle().generateKey(ED25519, true, ['sign', 'verify']);
+    const publicKey = await subtle().exportKey('jwk', pair.publicKey);
+    const privateKey = await subtle().exportKey('jwk', pair.privateKey);
+    const id = keyId ?? (await keyIdOf(publicKey));
+    return { keyId: id, signer: await ed25519Signer(id, pair.privateKey), publicKey, privateKey };
+}
+export async function ed25519Signer(keyId, privateKey) {
+    const key = isCryptoKey(privateKey)
+        ? privateKey
+        : await subtle().importKey('jwk', privateKey, ED25519, false, ['sign']);
+    return { keyId, sign: async (data) => new Uint8Array(await subtle().sign(ED25519, key, data)) };
+}
+export async function ed25519Keyring(keys) {
+    const imported = new Map();
+    for (const [keyId, key] of Object.entries(keys)) {
+        imported.set(keyId, isCryptoKey(key) ? key : await subtle().importKey('jwk', key, ED25519, false, ['verify']));
+    }
+    return {
+        async verify(keyId, data, signature) {
+            const key = imported.get(keyId);
+            if (!key)
+                return false;
+            try {
+                return await subtle().verify(ED25519, key, signature, data);
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+export async function contextDigest(content) {
+    const text = canonicalJson({ format: 'nexus-context-signature', formatVersion: 1, ...content });
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(text));
+    return `sha256:${hexOf(new Uint8Array(digest))}`;
+}
+export async function signDigest(signer, digest, at) {
+    const signature = await signer.sign(new TextEncoder().encode(digest));
+    return {
+        keyId: signer.keyId,
+        algorithm: 'Ed25519',
+        digest,
+        signature: toBase64Url(signature),
+        signedAt: at.toISOString(),
+    };
+}
+export async function verifiedBy(keyring, digest, signatures = []) {
+    const data = new TextEncoder().encode(digest);
+    for (const signature of signatures) {
+        if (signature?.algorithm !== 'Ed25519' || signature.digest !== digest)
+            continue;
+        let bytes;
+        try {
+            bytes = fromBase64Url(signature.signature);
+        }
+        catch {
+            continue;
+        }
+        if (await keyring.verify(signature.keyId, data, bytes))
+            return signature;
+    }
+    return undefined;
+}
+async function keyIdOf(publicKey) {
+    const digest = await subtle().digest('SHA-256', new TextEncoder().encode(String(publicKey.x)));
+    return hexOf(new Uint8Array(digest).subarray(0, 8));
+}
+function hexOf(bytes) {
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+function isCryptoKey(value) {
+    return typeof value.algorithm === 'object' && Array.isArray(value.usages);
+}
+function toBase64Url(bytes) {
+    return encodeBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function fromBase64Url(text) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/');
+    return decodeBase64(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+}

package/dist/core/secure-stream.js

@@ -1,3 +1,4 @@
+import { utf8Length } from '../utils/ids.js';
 import { redactSensitiveText } from '../security/output-guard.js';
 const MAX_BUFFERED_STREAM_BYTES = 1_048_576;
 const MAX_BUFFERED_STREAM_CHUNKS = 100_000;
@@ -21,13 +22,13 @@ export function protectStreamOutput(stream, security, requestSignal) {
                 }
                 if (chunk.type === 'text' && chunk.content) {
                     bufferedText += chunk.content;
-                    bufferedBytes += Buffer.byteLength(chunk.content);
+                    bufferedBytes += utf8Length(chunk.content);
                 }
                 else if (chunk.type === 'error' && chunk.error) {
-                    bufferedBytes += Buffer.byteLength(chunk.error);
+                    bufferedBytes += utf8Length(chunk.error);
                 }
                 else if (chunk.type === 'tool_call' && chunk.toolCall) {
-                    bufferedBytes += Buffer.byteLength(chunk.toolCall.function.arguments);
+                    bufferedBytes += utf8Length(chunk.toolCall.function.arguments);
                     bufferedToolCalls.push(chunk.toolCall);
                 }
                 if (bufferedBytes > MAX_BUFFERED_STREAM_BYTES) {

package/dist/doctor/index.d.ts

@@ -42,8 +42,10 @@ export interface DoctorDeployment {
     replicas: number;
     /**
      * The stores and shared state it uses, by any name: a checkpointer, the operation store, the
-     * server's state, tenant usage, a rate-limit store, a circuit store, a cache. Each is reported when
-     * it keeps its state in process memory, where each replica would see only its own.
+     * server's state, tenant usage, a rate-limit store, a circuit store, a cache, a tracer. Each is
+     * reported when it keeps its state in process memory, where each replica would see only its own,
+     * and when it lacks an opt-in setting a deployment needs: a Redis operation store without its
+     * dispatch index, or a tracer writing to a persistent store without incremental tracing.
      */
     stores?: Record<string, unknown>;
 }

package/dist/doctor/index.js

@@ -54,6 +54,7 @@ export async function diagnose(options = {}) {
     await run('queue', 'Operation queue and leases', () => queueCheck(options.operations, now(), options.maxQueueAgeMs));
     await run('health', 'Provider health', () => healthCheck(options.ai));
     await run('topology', 'Settings that only work in one process', () => topologyCheck(options.deployment));
+    await run('settings', 'Opt-in settings a deployment needs', () => settingsCheck(options.deployment));
     const failures = checks.filter((check) => check.status === 'fail').length;
     const warnings = checks.filter((check) => check.status === 'warn').length;
     return { checks, ok: failures === 0, failures, warnings };
@@ -235,3 +236,31 @@ function topologyCheck(deployment) {
         hint: 'Use the Redis, Postgres, or SQLite adapter for each, or run one replica.',
     };
 }
+function settingsCheck(deployment) {
+    const stores = Object.entries(deployment?.stores ?? {});
+    if (stores.length === 0)
+        return { status: 'skip', detail: 'No stores described.' };
+    const findings = [];
+    const hints = new Set();
+    for (const [name, value] of stores) {
+        const kind = kindOf(value);
+        if (kind === 'RedisOperationStore' && value.indexed === false) {
+            findings.push(`${name} is a RedisOperationStore without index: true, so finding queued work reads every record and a long queue slows every claim`);
+            hints.add('Give the Redis operation store index: true once every worker sharing its prefix runs 2.2 or later, then call reindex() once.');
+        }
+        if (kind === 'Tracer') {
+            const tracer = value;
+            const store = kindOf(tracer.store);
+            if (tracer.incremental === false && store && store !== 'MemoryTraceStore') {
+                findings.push(`${name} writes to a ${store} without incremental, so a trace is written when its root finishes and a replica that dies mid-run loses it`);
+                hints.add('Create the Tracer with incremental: true, and close what a dead process left with closeAbandonedRuns().');
+            }
+        }
+    }
+    if (findings.length === 0)
+        return { status: 'ok', detail: 'No store lacks a setting a deployment needs.' };
+    return { status: 'warn', detail: `${findings.join('; ')}.`, hint: [...hints].join(' ') };
+}
+function kindOf(value) {
+    return value?.constructor?.name;
+}

package/dist/embeddings/adapters.js

@@ -1,3 +1,4 @@
+import { decodeBase64 } from '../utils/base64.js';
 import { createProviderHttpError, toNexusProviderError } from '../providers/errors.js';
 import { EmbeddingProviderResponseError } from './errors.js';
 class HttpEmbeddingProvider {
@@ -31,7 +32,7 @@ class HttpEmbeddingProvider {
     }
 }
 function decodeBase64Vector(value) {
-    const bytes = Buffer.from(value, 'base64');
+    const bytes = decodeBase64(value);
     const floats = new Float32Array(bytes.buffer, bytes.byteOffset, Math.floor(bytes.byteLength / 4));
     return Array.from(floats);
 }

package/dist/evals/judge.js

@@ -1,4 +1,4 @@
-import { createHash } from 'node:crypto';
+import { sha256Hex } from '../utils/sha256.js';
 import { withProvenance } from '../evaluate/provenance.js';
 const DEFAULT_SYSTEM_PROMPT = [
     'You are a careful evaluation judge.',
@@ -64,10 +64,7 @@ export class LLMJudge {
             name: options.key ?? 'judge',
             judge: {
                 model: this.options.model,
-                promptVersion: createHash('sha256')
-                    .update(this.options.systemPrompt ?? 'default')
-                    .digest('hex')
-                    .slice(0, 12),
+                promptVersion: sha256Hex(this.options.systemPrompt ?? 'default').slice(0, 12),
                 temperature: this.options.temperature ?? 0,
             },
             ...(this.options.rubric ? { rubric: this.options.rubric } : {}),

package/dist/evaluate/cache.d.ts

@@ -42,20 +42,6 @@ export declare class MemoryEvaluationCache implements EvaluationCache {
     /** Drops every output. */
     clear(): void;
 }
-/**
- * Target outputs as JSON files in a directory, one per key, so a CI job keeps them between runs by
- * caching the directory. Writes go through a temporary file and a rename, so a reader never sees half
- * an entry. Outputs must survive `JSON.stringify()`.
- */
-export declare class FileEvaluationCache implements EvaluationCache {
-    private readonly directory;
-    constructor(directory: string);
-    /** The output under a key, or `undefined` when there is none or its file cannot be read. */
-    get(key: string): Promise<CachedOutput | undefined>;
-    /** Writes an output under a key. */
-    set(key: string, value: CachedOutput): Promise<void>;
-    private fileOf;
-}
 /**
  * A fingerprint for whatever decides a target's output — a model name, a prompt version, a
  * temperature, a context bundle version — as `f` and 16 hex digits of a SHA-256 over its canonical

package/dist/evaluate/cache.js

@@ -28,36 +28,6 @@ export class MemoryEvaluationCache {
         this.entries.clear();
     }
 }
-export class FileEvaluationCache {
-    directory;
-    constructor(directory) {
-        this.directory = directory;
-    }
-    async get(key) {
-        const { readFile } = await import('node:fs/promises');
-        try {
-            return JSON.parse(await readFile(await this.fileOf(key), 'utf8'));
-        }
-        catch {
-            return undefined;
-        }
-    }
-    async set(key, value) {
-        const { mkdir, rename, writeFile } = await import('node:fs/promises');
-        const path = await import('node:path');
-        const file = await this.fileOf(key);
-        await mkdir(path.dirname(file), { recursive: true });
-        const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
-        await writeFile(temporary, JSON.stringify(value), 'utf8');
-        await rename(temporary, file);
-    }
-    async fileOf(key) {
-        if (!/^[0-9a-f]{16,}$/.test(key))
-            throw new RangeError('An evaluation cache key is a hex string');
-        const path = await import('node:path');
-        return path.join(this.directory, key.slice(0, 2), `${key}.json`);
-    }
-}
 export async function fingerprintOf(value) {
     return `f${(await sha256(canonicalJson(value))).slice(0, 16)}`;
 }

package/dist/evaluate/file-cache.d.ts

@@ -0,0 +1,15 @@
+import type { CachedOutput, EvaluationCache } from './cache.js';
+/**
+ * Target outputs as JSON files in a directory, one per key, so a CI job keeps them between runs by
+ * caching the directory. Writes go through a temporary file and a rename, so a reader never sees half
+ * an entry. Outputs must survive `JSON.stringify()`.
+ */
+export declare class FileEvaluationCache implements EvaluationCache {
+    private readonly directory;
+    constructor(directory: string);
+    /** The output under a key, or `undefined` when there is none or its file cannot be read. */
+    get(key: string): Promise<CachedOutput | undefined>;
+    /** Writes an output under a key. */
+    set(key: string, value: CachedOutput): Promise<void>;
+    private fileOf;
+}

package/dist/evaluate/file-cache.js

@@ -0,0 +1,30 @@
+export class FileEvaluationCache {
+    directory;
+    constructor(directory) {
+        this.directory = directory;
+    }
+    async get(key) {
+        const { readFile } = await import('node:fs/promises');
+        try {
+            return JSON.parse(await readFile(await this.fileOf(key), 'utf8'));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async set(key, value) {
+        const { mkdir, rename, writeFile } = await import('node:fs/promises');
+        const path = await import('node:path');
+        const file = await this.fileOf(key);
+        await mkdir(path.dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.${Date.now()}.tmp`;
+        await writeFile(temporary, JSON.stringify(value), 'utf8');
+        await rename(temporary, file);
+    }
+    async fileOf(key) {
+        if (!/^[0-9a-f]{16,}$/.test(key))
+            throw new RangeError('An evaluation cache key is a hex string');
+        const path = await import('node:path');
+        return path.join(this.directory, key.slice(0, 2), `${key}.json`);
+    }
+}

package/dist/evaluate/index.d.ts

@@ -3,6 +3,7 @@ export { contentVersion, createDataset, type CreateDatasetOptions, datasetFromTr
 export { completed, contains, embeddingSimilarity, exactMatch, mustNotMatch, pairwise, passRate, recallAtK, reciprocalRank, type RetrievalEvaluatorOptions, totalCost, trajectory, type TrajectoryOptions, underCost, underLatency, } from './evaluators.js';
 export { AnnotationQueue, type AnnotationQueueOptions, evaluateOnline, type OnlineEvaluationOptions, type OnlineEvaluationReport, type ReviewAnswer, type ReviewItem, type ReviewQuestion, } from './review.js';
 export { evaluate, type EvaluateOptions, type EvaluationTarget, stats, summarize } from './run.js';
-export { type CachedOutput, type EvaluationCache, evaluationCacheKey, FileEvaluationCache, fingerprintOf, MemoryEvaluationCache, type MemoryEvaluationCacheOptions, } from './cache.js';
+export { type CachedOutput, type EvaluationCache, evaluationCacheKey, fingerprintOf, MemoryEvaluationCache, type MemoryEvaluationCacheOptions, } from './cache.js';
+export { FileEvaluationCache } from './file-cache.js';
 export type { Dataset, DatasetExample, DatasetStore, EvaluationContext, EvaluationScore, Evaluator, ExampleResult, Experiment, ExperimentStore, MetricSummary, SummaryEvaluator, } from '../types/evaluate.js';
 export { withProvenance } from './provenance.js';

package/dist/evaluate/index.js

@@ -3,5 +3,6 @@ export { contentVersion, createDataset, datasetFromTraces, FileDatasetStore, Fil
 export { completed, contains, embeddingSimilarity, exactMatch, mustNotMatch, pairwise, passRate, recallAtK, reciprocalRank, totalCost, trajectory, underCost, underLatency, } from './evaluators.js';
 export { AnnotationQueue, evaluateOnline, } from './review.js';
 export { evaluate, stats, summarize } from './run.js';
-export { evaluationCacheKey, FileEvaluationCache, fingerprintOf, MemoryEvaluationCache, } from './cache.js';
+export { evaluationCacheKey, fingerprintOf, MemoryEvaluationCache, } from './cache.js';
+export { FileEvaluationCache } from './file-cache.js';
 export { withProvenance } from './provenance.js';

package/dist/evaluate/review.js

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { randomHex } from '../utils/ids.js';
 export class AnnotationQueue {
     options;
     items = new Map();
@@ -9,7 +9,7 @@ export class AnnotationQueue {
     }
     enqueue(subject, metadata) {
         const item = {
-            id: `review-${randomBytes(6).toString('hex')}`,
+            id: `review-${randomHex(6)}`,
             subject,
             rubric: this.options.rubric,
             status: 'pending',

package/dist/evaluate/run.js

@@ -1,4 +1,4 @@
-import { randomBytes } from 'node:crypto';
+import { randomHex } from '../utils/ids.js';
 import { NEXUS_VERSION } from '../version.js';
 import { evaluationCacheKey } from './cache.js';
 import { declaredProvenance } from './provenance.js';
@@ -29,7 +29,7 @@ export async function evaluate(target, dataset, evaluators, options = {}) {
     for (const evaluator of options.summary ?? [])
         summary.push(...(await evaluator(results)));
     const experiment = {
-        id: `exp-${randomBytes(6).toString('hex')}`,
+        id: `exp-${randomHex(6)}`,
         name: options.name ?? `${dataset.name} ${startedAt}`,
         dataset: { name: dataset.name, version: dataset.version },
         startedAt,

package/dist/evaluate/threads.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Evaluation of whole conversations. A simulated user holds a conversation with an agent for each
+ * goal in a dataset, and thread evaluators score the conversation: whether the goal was met, each
+ * turn, and the turn where it went wrong. A multi-turn agent is then compared between versions as a
+ * single-turn one is, with `evaluate()` and `compareExperiments()`.
+ */
+import type { LLMJudge } from '../evals/judge.js';
+import type { Evaluator } from '../types/evaluate.js';
+import type { CompletionRequest, Message } from '../types/messages.js';
+import type { EvaluationTarget } from './run.js';
+/** One turn of a conversation. */
+export interface ThreadTurn {
+    /** Who spoke. */
+    role: 'user' | 'assistant';
+    /** What they said. */
+    content: string;
+    /** For an assistant turn, how long the agent took, in milliseconds. */
+    latencyMs?: number;
+    /**
+     * For an assistant turn, every message the agent added: its tool calls, their results, and the
+     * answer. The agent is given them back on later turns, and an evaluator can read its trajectory.
+     */
+    messages?: Message[];
+}
+/** Why a conversation ended. */
+export type ThreadEnding = 'goal' | 'gave-up' | 'max-turns' | 'error';
+/** A finished conversation: what a conversation target returns, and what thread evaluators read. */
+export interface Thread {
+    /** Every turn, in order. */
+    turns: ThreadTurn[];
+    /**
+     * `goal` when the user said its goal was met, `gave-up` when it said it never would be, `max-turns`
+     * when the turn limit ended it, and `error` when the agent failed.
+     */
+    ended: ThreadEnding;
+    /** The agent's error, when it failed. */
+    error?: string;
+}
+/** What a conversation is about: the user's goal, and optionally who they are and how they open. */
+export interface ThreadInputs {
+    /** What the user wants, in their words or the dataset's. */
+    goal: string;
+    /** Who the user is and how they talk, such as "an impatient customer who writes in short lines". */
+    persona?: string;
+    /** The user's first message, instead of letting the simulated user write it. */
+    opening?: string;
+}
+/** What a simulated user sees when it writes its next message. */
+export interface SimulatedUserContext {
+    /** The goal. */
+    goal: string;
+    /** The persona, when the example gives one. */
+    persona?: string;
+    /** The conversation so far. Empty for the first message. */
+    turns: readonly ThreadTurn[];
+    /** Aborted when the evaluation is cancelled or times out. */
+    signal?: AbortSignal;
+}
+/** A simulated user's move: its next message, or the end of the conversation and why. */
+export type SimulatedUserReply = {
+    message: string;
+} | {
+    done: 'goal' | 'gave-up';
+};
+/** Plays the user in a conversation. */
+export interface SimulatedUser {
+    /** The next move, given the conversation so far. */
+    next(context: SimulatedUserContext): Promise<SimulatedUserReply> | SimulatedUserReply;
+}
+/** A model client, as the judges take one. */
+export interface SimulatedUserClient {
+    /** Runs one completion. */
+    complete(request: CompletionRequest): Promise<{
+        content: string;
+    }>;
+}
+/** Options for `simulatedUser()`. */
+export interface SimulatedUserOptions {
+    /** The client the user's model is called through. */
+    client: SimulatedUserClient;
+    /** The model that plays the user. */
+    model: string;
+    /** A persona for every conversation, when the examples give none. */
+    persona?: string;
+    /** Sampling temperature. Defaults to 0, so a conversation repeats. */
+    temperature?: number;
+    /** Output token limit for each message. Defaults to 300. */
+    maxTokens?: number;
+    /** Replaces the instructions the model is given. `{goal}` and `{persona}` are filled in. */
+    instructions?: string;
+}
+/**
+ * A simulated user driven by a model: it is told the goal and the persona, sees the conversation
+ * with the roles turned around, and writes the next message, or says it is done and why.
+ */
+export declare function simulatedUser(options: SimulatedUserOptions): SimulatedUser;
+/**
+ * A user that follows a script, for deterministic tests: its messages in order, then `done`. A
+ * function decides each move itself.
+ */
+export declare function scriptedUser(script: {
+    messages: readonly string[];
+    done?: 'goal' | 'gave-up';
+} | SimulatedUser['next']): SimulatedUser;
+/** What a thread agent is told besides the conversation. */
+export interface ThreadAgentContext<I extends ThreadInputs = ThreadInputs> {
+    /** The example's inputs. */
+    inputs: I;
+    /** The turn, counted from 1. */
+    turn: number;
+    /** Names this conversation, the same on every turn and new for every conversation: a thread id. */
+    conversationId: string;
+    /** Aborted when the evaluation is cancelled or times out. */
+    signal?: AbortSignal;
+}
+/**
+ * What a thread agent answers: the reply, or the reply and every message the agent added on the way,
+ * such as its tool calls and their results. Those are given back to it on later turns.
+ */
+export type ThreadAgentReply = string | {
+    content: string;
+    messages?: Message[];
+};
+/**
+ * The agent a conversation target talks to. It is given the conversation so far, with its own earlier
+ * turns as it recorded them, and answers the user's newest message.
+ */
+export type ThreadAgent<I extends ThreadInputs = ThreadInputs> = (messages: readonly Message[], context: ThreadAgentContext<I>) => Promise<ThreadAgentReply> | ThreadAgentReply;
+/** Options for `conversationTarget()`. */
+export interface ConversationTargetOptions<I extends ThreadInputs = ThreadInputs> {
+    /** The user, or a user per example, such as one with the example's own persona. */
+    user: SimulatedUser | ((inputs: I) => SimulatedUser);
+    /** The most user messages a conversation may have. Defaults to 10. */
+    maxTurns?: number;
+}
+/**
+ * An `evaluate()` target that holds a conversation per example: the simulated user speaks, the agent
+ * answers, until the user says it is done or the turn limit is reached. It returns the `Thread`.
+ */
+export declare function conversationTarget<I extends ThreadInputs = ThreadInputs>(agent: ThreadAgent<I>, options: ConversationTargetOptions<I>): EvaluationTarget<I>;
+/** A graph a thread agent can drive: one that takes `{ messages }`, as `createAgent()` builds. */
+export interface ThreadGraph {
+    /** Runs one turn. */
+    invoke(input: {
+        messages: Message[];
+    }, options?: {
+        threadId?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        state: unknown;
+    }>;
+}
+/**
+ * An agent from `createAgent()`, or any graph that takes `{ messages }` and ends with an `answer`, as
+ * a thread agent. Each turn runs on the conversation's thread with the transcript so far, and the
+ * messages the run added to its `messages` are recorded with the turn. The agent therefore sees its
+ * own tool calls on later turns, as it does with a real user, without needing a checkpointer.
+ */
+export declare function graphThreadAgent(graph: ThreadGraph): ThreadAgent;
+/** The conversation as text, for a judge or a person. */
+export declare function formatThread(thread: Thread): string;
+/**
+ * Whether the user said its goal was met: 1 when the conversation ended on `goal`, otherwise 0, with
+ * how it ended as the comment. Key `goal_reached`.
+ */
+export declare function goalReached(): Evaluator<ThreadInputs>;
+/**
+ * Whether the goal was met, in a judge's opinion of the whole conversation, not the user's. Key
+ * `goal_completion`, with the judge's rationale as the comment.
+ */
+export declare function goalCompletion(judge: Pick<LLMJudge, 'evaluate'>): Evaluator<ThreadInputs>;
+/** How many times the assistant spoke: fewer is better. Key `turns`; compare with `lowerIsBetter: ['turns']`. */
+export declare function turnCount(): Evaluator<ThreadInputs>;
+/** Options for `turnScores()`. */
+export interface TurnScoresOptions {
+    /** The score's key. Defaults to `turn_score`. */
+    key?: string;
+    /** A turn scoring below this went wrong. Defaults to 0.5. */
+    threshold?: number;
+}
+/**
+ * Scores every assistant turn with an evaluator of single answers, and the conversation by their
+ * mean. The evaluator sees each turn as an example of its own: the user's message as the input, the
+ * conversation before it in `metadata.history`, and the turn as the output. The score's metadata holds
+ * each turn's score, and `wentWrongAt`, the first turn below the threshold, counted from 1.
+ */
+export declare function turnScores<I = unknown>(evaluator: Evaluator<I>, options?: TurnScoresOptions): Evaluator<ThreadInputs>;