nexus-ai-pro 2.2.0 → 2.3.0

package/dist/rag/pipeline.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Durable ingestion: keeps a vector store, and any keyword indexes beside it, in step with a corpus
+ * that changes.
+ *
+ * A manifest in any `Store` records, for every document, the version of its content, the chunking,
+ * the embedding model, and each chunk's version. A run reads the corpus, embeds only the chunks that
+ * are new or changed, deletes the chunks a document no longer has and the documents the corpus no
+ * longer has, and writes every change idempotently, before the manifest records it. A run that dies
+ * halfway leaves a manifest that says exactly what finished; the next run skips it, and inside a
+ * durable operation it starts at the document it stopped on.
+ */
+import type { EmbeddingProvider, VectorStore } from '../hallucination/retrieval.js';
+import type { OperationContext, OperationExecutor } from '../types/operations.js';
+import type { Store } from '../types/store.js';
+import { type DocumentSource, type IngestionOptions } from './ingestion.js';
+import type { SparseRetriever } from './retrievers.js';
+/** A source of documents: a loader, an array, or any iterable, read once per run. */
+export type IngestionSource = AsyncIterable<DocumentSource> | Iterable<DocumentSource>;
+/** Options for `createIngestionPipeline()`. */
+export interface IngestionPipelineOptions {
+    /** Names the pipeline. Its manifest is kept under this name, so two pipelines never share one. */
+    name: string;
+    /**
+     * Where the manifest is kept: any `Store`, so it lives in memory, Redis, Postgres, or SQLite. It
+     * holds one item per document, and a `MemoryStore` keeps 10,000 items unless given a larger
+     * `maxItems`: a manifest that forgets a document re-embeds it.
+     */
+    manifest: Store;
+    /** The vector store chunks are embedded into. */
+    vectors: VectorStore;
+    /**
+     * Keyword indexes kept in step, such as an `ElasticsearchKeywordIndex`. A `PostgresKeywordIndex`
+     * that is `shared` needs no place here: the vector store's writes already reach it.
+     */
+    keywords?: readonly SparseRetriever[];
+    /** Embeds chunk texts. Called only for chunks that are new or changed. */
+    embed: EmbeddingProvider;
+    /** The embedding model, recorded with every document: a different one re-embeds everything. */
+    embeddingModel: string;
+    /** How documents are split. Different options re-chunk every document. */
+    chunking?: IngestionOptions;
+    /** Documents read, embedded, and recorded together. Defaults to 64. */
+    batchSize?: number;
+}
+/** Options for one run. */
+export interface IngestionRunOptions {
+    /** Stops the run between batches. Everything recorded so far stays recorded. */
+    signal?: AbortSignal;
+    /**
+     * Removes the documents the manifest has and this run did not see, with their chunks. Defaults to
+     * true: the source is the whole corpus. Turn it off when a run loads only part of it.
+     */
+    deleteMissing?: boolean;
+    /** Called after each batch, with the run so far. */
+    onProgress?: (progress: IngestionReport) => void;
+    /**
+     * The durable operation the run belongs to, when it runs inside an `OperationRunner`. After every
+     * batch the run records how far it got with `heartbeat()`, and a later attempt reads it from
+     * `previousHeartbeat` and skips straight past what was finished.
+     */
+    operation?: Pick<OperationContext, 'heartbeat' | 'previousHeartbeat'>;
+}
+/** What a run did. */
+export interface IngestionReport {
+    /** Documents read. */
+    documents: number;
+    /** Documents whose content, chunking, and model were all as recorded, so nothing was done. */
+    unchanged: number;
+    /** Documents the manifest did not have. */
+    added: number;
+    /** Documents that changed. */
+    updated: number;
+    /** Documents removed because the corpus no longer has them. */
+    deleted: number;
+    /** Chunks embedded and written. */
+    chunksEmbedded: number;
+    /** Chunks of changed documents whose text did not change, so their embedding was kept. */
+    chunksKept: number;
+    /** Chunks removed. */
+    chunksDeleted: number;
+    /** Documents a resumed run skipped because an earlier attempt had finished them. */
+    resumed: number;
+}
+/** What the manifest records for one document. */
+export interface IngestedDocument {
+    /** The document's id. */
+    id: string;
+    /** A hash of its text, source, and metadata. */
+    version: string;
+    /** A hash of the chunking options it was split with. */
+    chunking: string;
+    /** The embedding model its chunks were embedded with. */
+    model: string;
+    /** Each chunk's id, with the hash of its text: the chunk's version. */
+    chunks: Record<string, string>;
+    /** When it was last written, as ISO-8601. */
+    updatedAt: string;
+}
+/** A pipeline: run it as often as the corpus changes. */
+export interface IngestionPipeline {
+    /** Brings the stores in step with the documents a source yields. */
+    run(source: IngestionSource | readonly IngestionSource[], options?: IngestionRunOptions): Promise<IngestionReport>;
+    /** What the manifest records for a document, or `undefined`. */
+    document(id: string): Promise<IngestedDocument | undefined>;
+    /** Removes documents by id, with their chunks, from every store and the manifest. */
+    remove(ids: readonly string[]): Promise<number>;
+}
+/**
+ * Builds a pipeline that keeps the stores in step with a corpus, re-embedding only what changed.
+ *
+ * Documents need an `id` (or a `source`), which is what ties a document to its earlier version. A
+ * chunk's id is its document's id and a hash of its text, so a chunk whose text did not change keeps
+ * its embedding wherever it moved. Chunks are cut by length, within each Markdown section when
+ * `splitOnMarkdownHeadings` is on, so an edit re-embeds the chunks of its section from the edit on,
+ * and a section added or removed leaves the others alone. One run at a time per pipeline; an
+ * operation's idempotency key enforces that across workers.
+ *
+ * ```ts
+ * const pipeline = createIngestionPipeline({
+ *   name: 'help-center',
+ *   manifest: store,
+ *   vectors: new PostgresVectorStore(pool, { dimensions: 1536 }),
+ *   embed,
+ *   embeddingModel: 'text-embedding-3-small',
+ * });
+ * const report = await pipeline.run(loadDirectory('./docs'));
+ * ```
+ */
+export declare function createIngestionPipeline(options: IngestionPipelineOptions): IngestionPipeline;
+/**
+ * The pipeline as the executor of a durable operation: submit it to an `OperationRunner`, and an
+ * attempt that dies halfway is recovered by another worker, which starts at the document the first
+ * one stopped on.
+ *
+ * ```ts
+ * const runner = new OperationRunner({ store: new RedisOperationStore(redis), retry: { maxAttempts: 5 } });
+ * await runner.submit(ingestionExecutor(pipeline, () => loadDirectory('./docs')), { idempotencyKey: 'help-center' });
+ * ```
+ */
+export declare function ingestionExecutor(pipeline: IngestionPipeline, source: () => IngestionSource | readonly IngestionSource[], options?: Omit<IngestionRunOptions, 'operation' | 'signal'>): OperationExecutor<IngestionReport>;

package/dist/rag/pipeline.js

@@ -0,0 +1,187 @@
+import { ingestDocuments } from './ingestion.js';
+export function createIngestionPipeline(options) {
+    const batchSize = options.batchSize ?? 64;
+    if (!(Number.isInteger(batchSize) && batchSize > 0))
+        throw new RangeError('batchSize must be a positive integer');
+    const namespace = ['nexus', 'ingestion', options.name, 'documents'];
+    const keywords = options.keywords ?? [];
+    const chunkingVersion = stableJson(options.chunking ?? {});
+    const read = async (id) => (await options.manifest.get(namespace, id))?.value;
+    const removeChunks = async (ids) => {
+        if (ids.length === 0)
+            return;
+        await Promise.all([options.vectors.delete(ids), ...keywords.map((index) => index.delete(ids))]);
+    };
+    const remove = async (ids) => {
+        let chunks = 0;
+        for (const id of ids) {
+            const recorded = await read(id);
+            if (!recorded)
+                continue;
+            const chunkIds = Object.keys(recorded.chunks);
+            await removeChunks(chunkIds);
+            await options.manifest.delete(namespace, id);
+            chunks += chunkIds.length;
+        }
+        return chunks;
+    };
+    return {
+        document: read,
+        async remove(ids) {
+            await remove(ids);
+            return ids.length;
+        },
+        async run(source, runOptions = {}) {
+            const report = {
+                documents: 0,
+                unchanged: 0,
+                added: 0,
+                updated: 0,
+                deleted: 0,
+                chunksEmbedded: 0,
+                chunksKept: 0,
+                chunksDeleted: 0,
+                resumed: 0,
+            };
+            const previous = runOptions.operation?.previousHeartbeat;
+            const skip = previous?.pipeline === options.name ? previous.documents : 0;
+            const seen = new Set();
+            let batch = [];
+            const flush = async () => {
+                if (batch.length === 0)
+                    return;
+                const current = batch;
+                batch = [];
+                const versions = await Promise.all(current.map(({ document }) => hashText(stableJson([document.text, document.source ?? null, document.metadata ?? null]))));
+                const recorded = await Promise.all(current.map(({ id }) => read(id)));
+                const writes = [];
+                const stale = [];
+                const toEmbed = [];
+                for (const [index, { document, id }] of current.entries()) {
+                    const version = versions[index];
+                    const before = recorded[index];
+                    if (before &&
+                        before.version === version &&
+                        before.chunking === chunkingVersion &&
+                        before.model === options.embeddingModel) {
+                        report.unchanged += 1;
+                        continue;
+                    }
+                    if (before)
+                        report.updated += 1;
+                    else
+                        report.added += 1;
+                    const split = ingestDocuments([{ ...document, id }], options.chunking).chunks;
+                    const hashes = await Promise.all(split.map((chunk) => hashText(stableJson([chunk.content, document.metadata ?? null]))));
+                    const used = new Map();
+                    const chunks = split.map((chunk, position) => {
+                        const base = `${id}#${hashes[position].slice(0, 12)}`;
+                        const count = (used.get(base) ?? 0) + 1;
+                        used.set(base, count);
+                        return { ...chunk, id: count === 1 ? base : `${base}-${count}` };
+                    });
+                    const reusable = before && before.model === options.embeddingModel ? before.chunks : {};
+                    for (const [position, chunk] of chunks.entries()) {
+                        if (reusable[chunk.id] === hashes[position])
+                            report.chunksKept += 1;
+                        else
+                            toEmbed.push(chunk);
+                    }
+                    const kept = new Set(chunks.map((chunk) => chunk.id));
+                    if (before)
+                        stale.push(...Object.keys(before.chunks).filter((chunkId) => !kept.has(chunkId) || !reusable[chunkId]));
+                    writes.push({ id, version, chunks, hashes });
+                }
+                if (toEmbed.length > 0) {
+                    const vectors = await options.embed(toEmbed.map((chunk) => chunk.content));
+                    if (vectors.length !== toEmbed.length) {
+                        throw new RangeError(`The embedding function returned ${vectors.length} vectors for ${toEmbed.length} texts`);
+                    }
+                    await Promise.all([
+                        options.vectors.add(toEmbed.map((chunk, index) => ({ ...chunk, embedding: vectors[index] }))),
+                        ...keywords.map((index) => index.add(toEmbed)),
+                    ]);
+                    report.chunksEmbedded += toEmbed.length;
+                }
+                const embeddedIds = new Set(toEmbed.map((chunk) => chunk.id));
+                const removable = stale.filter((chunkId) => !embeddedIds.has(chunkId));
+                await removeChunks(removable);
+                report.chunksDeleted += removable.length;
+                const updatedAt = new Date().toISOString();
+                await Promise.all(writes.map(({ id, version, chunks, hashes }) => options.manifest.put(namespace, id, {
+                    id,
+                    version,
+                    chunking: chunkingVersion,
+                    model: options.embeddingModel,
+                    chunks: Object.fromEntries(chunks.map((chunk, index) => [chunk.id, hashes[index]])),
+                    updatedAt,
+                })));
+                await runOptions.operation?.heartbeat({
+                    pipeline: options.name,
+                    documents: report.documents,
+                });
+                runOptions.onProgress?.({ ...report });
+            };
+            const sources = isSourceList(source) ? source : [source];
+            for (const loader of sources) {
+                for await (const document of loader) {
+                    runOptions.signal?.throwIfAborted();
+                    const id = document.id ?? document.source;
+                    if (!id)
+                        throw new TypeError('Durable ingestion needs a document id, or a source to use as one');
+                    seen.add(id);
+                    report.documents += 1;
+                    if (report.documents <= skip) {
+                        report.resumed += 1;
+                        continue;
+                    }
+                    batch.push({ document, id });
+                    if (batch.length >= batchSize)
+                        await flush();
+                }
+            }
+            runOptions.signal?.throwIfAborted();
+            await flush();
+            if (runOptions.deleteMissing !== false) {
+                const missing = [];
+                for (let offset = 0;; offset += 500) {
+                    const page = await options.manifest.search(namespace, { limit: 500, offset });
+                    for (const item of page)
+                        if (!seen.has(item.key))
+                            missing.push(item.key);
+                    if (page.length < 500)
+                        break;
+                }
+                for (const id of missing) {
+                    runOptions.signal?.throwIfAborted();
+                    report.chunksDeleted += await remove([id]);
+                    report.deleted += 1;
+                }
+                if (missing.length > 0)
+                    runOptions.onProgress?.({ ...report });
+            }
+            return report;
+        },
+    };
+}
+export function ingestionExecutor(pipeline, source, options = {}) {
+    return (context) => pipeline.run(source(), { ...options, signal: context.signal, operation: context });
+}
+async function hashText(text) {
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+    let hex = '';
+    for (const byte of new Uint8Array(digest).subarray(0, 16))
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+function stableJson(value) {
+    return JSON.stringify(value, (_key, entry) => entry && typeof entry === 'object' && !Array.isArray(entry)
+        ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)))
+        : entry);
+}
+function isSourceList(value) {
+    if (!Array.isArray(value))
+        return false;
+    const first = value[0];
+    return first !== undefined && typeof first === 'object' && first !== null && !('text' in first);
+}

package/dist/rag/rerankers.d.ts

@@ -0,0 +1,92 @@
+import type { Reranker } from './retrievers.js';
+/** Raised when a rerank API answers with an error. */
+export declare class RerankerError extends Error {
+    /** The HTTP status the API answered with. */
+    readonly status: number;
+    /** The API's response body, as text. */
+    readonly body?: string | undefined;
+    constructor(message: string, 
+    /** The HTTP status the API answered with. */
+    status: number, 
+    /** The API's response body, as text. */
+    body?: string | undefined);
+}
+/** What every HTTP reranker takes. */
+export interface RerankerHttpOptions {
+    /** Replaces the global `fetch`, for a proxy, retries, or tests. */
+    fetch?: typeof globalThis.fetch;
+    /** Headers added to every request. */
+    headers?: Record<string, string>;
+    /** Aborts a request that takes longer, in milliseconds. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Characters of each chunk sent. Defaults to 4,000. */
+    maxChunkCharacters?: number;
+}
+/** Options for a hosted rerank API. */
+export interface HostedRerankerOptions extends RerankerHttpOptions {
+    /** The API key. */
+    apiKey: string;
+    /** The rerank model, such as `rerank-v3.5`. */
+    model: string;
+    /** Replaces the API's endpoint, for a regional or proxied one. */
+    url?: string;
+}
+/** Options for `httpReranker()`: any rerank API, described by its request and its response. */
+export interface HttpRerankerOptions extends RerankerHttpOptions {
+    /** The endpoint. */
+    url: string;
+    /** The request body for a query and its passages. */
+    body: (query: string, passages: string[]) => unknown;
+    /** Reads the response: each passage's index and score. Passages it leaves out score 0. */
+    scores: (response: unknown) => ReadonlyArray<{
+        index: number;
+        score: number;
+    }>;
+}
+/**
+ * A reranker over any HTTP rerank API: you describe the request body and how to read the scores,
+ * and it handles the rest — truncation, the timeout, cancellation, errors, and scores put back in
+ * the order of the chunks.
+ */
+export declare function httpReranker(options: HttpRerankerOptions): Reranker;
+/** Cohere's rerank API (`/v2/rerank`), such as `rerank-v3.5`. */
+export declare function cohereReranker(options: HostedRerankerOptions): Reranker;
+/** Voyage AI's rerank API (`/v1/rerank`), such as `rerank-2`. */
+export declare function voyageReranker(options: HostedRerankerOptions): Reranker;
+/** Jina AI's rerank API (`/v1/rerank`), such as `jina-reranker-v2-base-multilingual`. */
+export declare function jinaReranker(options: HostedRerankerOptions): Reranker;
+/** Options for `teiReranker()`. */
+export interface TeiRerankerOptions extends RerankerHttpOptions {
+    /** The server, such as `http://localhost:8080`. */
+    url: string;
+}
+/**
+ * A cross-encoder served by Hugging Face's text-embeddings-inference, on your own machine or
+ * cluster: `docker run ... --model-id BAAI/bge-reranker-base`, then `teiReranker({ url })`. The
+ * scores are the model's own, from 0 to 1.
+ */
+export declare function teiReranker(options: TeiRerankerOptions): Reranker;
+/**
+ * A cross-encoder run in process: one score per (query, passage) pair, higher meaning more relevant.
+ * A model from an ONNX runtime or a transformers library fits it in a few lines, so the package
+ * depends on neither.
+ */
+export interface CrossEncoder {
+    /** Scores each pair, in order. */
+    score(pairs: ReadonlyArray<readonly [query: string, passage: string]>): Promise<readonly number[]> | readonly number[];
+}
+/** Options for `crossEncoderReranker()`. */
+export interface CrossEncoderRerankerOptions {
+    /** Pairs scored in one call. Defaults to 32. */
+    batchSize?: number;
+    /** Characters of each chunk scored. Defaults to 2,000. */
+    maxChunkCharacters?: number;
+    /** Maps raw logits to 0–1 with a sigmoid, for a model that returns logits. Defaults to false. */
+    sigmoid?: boolean;
+}
+/**
+ * A reranker over a cross-encoder you run in process: no network call, no per-query price, and the
+ * passages never leave the machine. Pairs are scored in batches, and the run's signal is checked
+ * between batches.
+ */
+export declare function crossEncoderReranker(model: CrossEncoder, options?: CrossEncoderRerankerOptions): Reranker;

package/dist/rag/rerankers.js

@@ -0,0 +1,97 @@
+import { linkSignals } from '../utils/signals.js';
+export class RerankerError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'RerankerError';
+    }
+}
+export 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 = 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 }));
+export 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),
+    });
+}
+export 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),
+    });
+}
+export 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),
+    });
+}
+export function teiReranker(options) {
+    return httpReranker({
+        ...options,
+        url: `${options.url.replace(/\/+$/, '')}/rerank`,
+        body: (query, texts) => ({ query, texts, raw_scores: false, truncate: true }),
+        scores: (response) => response,
+    });
+}
+export 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/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/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/server/assistant.js

@@ -81,8 +81,10 @@ export 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)