@dudousxd/nestjs-agent-rag 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -174,6 +174,32 @@ interface VectorStore {
      * `size` changed), or {@link VectorStore.remove remove} (orphaned).
      */
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * Read one document's chunks back — id, text, metadata — ordered by their position in the
+     * document, optionally paged with `limit`/`offset`.
+     *
+     * The gap this closes is that **the text a store holds is otherwise write-only**. Every other way
+     * back to it is a ranked query: {@link VectorStore.search} needs an embedding,
+     * {@link LexicalVectorStore.searchText} needs a query string, and both return whatever *matched*,
+     * in relevance order, capped at `topK`. Neither can answer "show me what was indexed for this
+     * document, in order" — the question you ask when retrieval returns the wrong passage and you need
+     * to know whether the chunker cut badly or the retriever chose badly. Without this, the only way to
+     * see stored text is to reach around the adapter into the backing engine, which is exactly the
+     * abstraction break a consumer adopts a store to avoid.
+     *
+     * Document-scoped rather than filter-scoped, matching {@link VectorStore.remove} and
+     * {@link VectorStore.updateMetadata}: ordering is the whole point, and "position within the
+     * document" is only meaningful once a document has been picked. Enumerate documents with
+     * {@link VectorStore.listDocuments} first when you need to sweep.
+     *
+     * An unknown `documentId` yields `[]`; it does not throw, matching `remove` and `updateMetadata`.
+     *
+     * NOT an access-control seam. It takes no metadata `filter` and applies none, so it cannot enforce
+     * one — a caller that gates retrieval on a metadata field (tenant, audience, collection) MUST
+     * resolve that gate itself before calling, exactly as it would before `remove`. It is deliberately
+     * shaped for an operator/debug surface, not for serving end users.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /**
      * The distinct source document ids currently indexed, optionally narrowed by a metadata `filter` —
      * {@link VectorStore.listDocuments} without the metadata. Use it when you only need the id set (a
@@ -271,9 +297,90 @@ interface IndexedDocument {
     id: string;
     metadata?: Record<string, unknown>;
 }
+/** One stored chunk, read back verbatim — what {@link VectorStore.listChunks} yields. */
+interface StoredChunk {
+    /** The chunk id: `${documentId}#<n>`, or the bare document id for a single-chunk document. */
+    id: string;
+    /** Zero-based position within the document, parsed from the id. A bare id is chunk `0`. */
+    index: number;
+    /** The chunk text as it was indexed — the exact string the embedding was computed from. */
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** Paging for {@link VectorStore.listChunks}. Omit both to read the whole document. */
+interface ListChunksOptions {
+    /** Max chunks to return, applied after ordering by {@link StoredChunk.index}. */
+    limit?: number;
+    /** Chunks to skip, applied after ordering. */
+    offset?: number;
+}
+/** Chunk `n` of `${documentId}#<n>`; a bare document id (single-chunk document) is `0`. */
+declare function chunkIndexOf(chunkId: string): number;
 /** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
 declare function documentIdOf(chunkId: string): string;
 
+/**
+ * What a retrieval was served BY — the static half of retrieval telemetry, separated from the
+ * emitting half (`retrieval-telemetry.ts`) so a store or a retriever can describe itself without
+ * importing anything that emits. That separation is not tidiness: `retrieval-telemetry.ts` imports
+ * the retrievers' shapes to detect them, and the retrievers import their descriptor kind, so putting
+ * both halves in one module would make every retriever ↔ telemetry edge a cycle.
+ */
+/** Which retrieval strategy answered. `unknown` is a retriever this package did not ship. */
+type RetrieverKind = 'embedding' | 'keyword' | 'lexical' | 'hybrid' | 'filtered' | 'reranking' | 'unknown';
+/** Which backend held the chunks. Omitted entirely for a retriever that holds its own (keyword). */
+type VectorStoreKind = 'memory' | 'pg' | 'redis';
+/**
+ * A retriever's (or a store's) self-description, as it appears on a retrieval event. Every field is
+ * optional because the describer is answering only for the layer it *is*: a store knows its backend
+ * and namespace but not which strategy queried it; `KeywordRetriever` knows its strategy but has no
+ * store at all.
+ */
+interface RetrievalDescriptor {
+    retriever?: RetrieverKind;
+    store?: VectorStoreKind;
+    /**
+     * The namespace the chunks live in — `PgVectorStore`'s table, `RedisVectorStore`'s RediSearch
+     * index. This is the STORE-level namespace, not a per-query metadata scope: a host that partitions
+     * one index into logical collections with a metadata filter (the usual multi-tenant shape) reports
+     * that through `InstrumentRetrieverOptions.collection`, which overrides this.
+     */
+    collection?: string;
+}
+/**
+ * The optional capability a store or retriever implements to appear on a retrieval event as
+ * something other than `unknown`. Deliberately NOT a member of `VectorStore` or of core's
+ * `Retriever`: both are implemented outside this package, and adding a required member to either
+ * would break every existing implementation on upgrade — for a field that only observability reads.
+ */
+interface DescribesRetrieval {
+    describeRetrieval(): RetrievalDescriptor;
+}
+/** Structural guard, so a `VectorStore`/`Retriever` is narrowed to the capability without a cast. */
+declare function describesRetrieval(value: unknown): value is DescribesRetrieval;
+/** A candidate's descriptor, or an empty one when it does not carry the capability. */
+declare function describeRetrieval(candidate: unknown): RetrievalDescriptor;
+/**
+ * The store half of a wrapped retriever's descriptor: the base's `store`/`collection` with its
+ * `retriever` dropped, so the wrapper can stamp its own strategy on top.
+ *
+ * `new FilteredRetriever(new EmbeddingRetriever(embedder, pg), scope)` therefore reports
+ * `{ retriever: 'filtered', store: 'pg', collection: 'agent_rag_chunks' }` rather than losing the
+ * store: which backend answered is the thing a "retrievals by store" panel exists to show, and a
+ * production wiring is almost always two or three wrappers deep.
+ */
+declare function describeSource(base: unknown): Omit<RetrievalDescriptor, 'retriever'>;
+/**
+ * The store half shared by EVERY leg of a composed retriever, or nothing when they disagree.
+ *
+ * A hybrid whose legs are the dense and lexical halves of the same RediSearch index (the shape
+ * `LexicalRetriever` exists for) genuinely was served by that one store, and reporting it is what
+ * makes the store breakdown add up. A hybrid fusing pgvector with an in-process BM25 index was not
+ * served by either alone, and picking the first leg would silently attribute every such retrieval to
+ * a store that answered half of it.
+ */
+declare function describeSharedSource(legs: readonly unknown[]): Omit<RetrievalDescriptor, 'retriever'>;
+
 /**
  * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter
  * for tests and small/embedded corpora; for production scale use `PgVectorStore` (or your own).
@@ -286,6 +393,12 @@ declare function documentIdOf(chunkId: string): string;
  */
 declare class MemoryVectorStore implements VectorStore {
     private readonly records;
+    /**
+     * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this
+     * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them
+     * apart on a dashboard.
+     */
+    describeRetrieval(): RetrievalDescriptor;
     upsert(records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     /**
@@ -296,6 +409,16 @@ declare class MemoryVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Insertion order is not document order — `upsert` stores whatever the caller passed, and a
+     * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index
+     * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the
+     * Map. A reference adapter that returned "usually ordered" would let a consumer ship a bug that
+     * only shows up on the store tests are NOT written against.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     removeMany(documentIds: string[]): Promise<void>;
     /**
@@ -356,6 +479,8 @@ declare class PgVectorStore implements VectorStore {
     private readonly table;
     private readonly dimensions;
     constructor(client: PgClient, options?: PgVectorStoreOptions);
+    /** Telemetry self-description — the table is the namespace a retrieval was served from. */
+    describeRetrieval(): RetrievalDescriptor;
     /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */
     ensureSchema(): Promise<void>;
     upsert(records: VectorRecord[]): Promise<void>;
@@ -374,6 +499,19 @@ declare class PgVectorStore implements VectorStore {
      */
     updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain
+     * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the
+     * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which
+     * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two
+     * adapters.
+     *
+     * `embedding` is left out of the projection: it is the widest column in the table and useless to a
+     * caller reading text back.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */
     listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;
     /** N documents in one statement — the set-based form of {@link PgVectorStore.remove}. */
@@ -463,6 +601,12 @@ declare class RedisVectorStore implements LexicalVectorStore {
     private readonly filterableFields;
     private readonly lexicalScorer;
     constructor(client: RedisSearchClient, options?: RedisVectorStoreOptions);
+    /**
+     * Telemetry self-description — the RediSearch INDEX, not the key prefix: the index is what both
+     * legs query, and two stores sharing one index (the dense and lexical halves of a hybrid) must
+     * report the same namespace or `describeSharedSource` would see them disagree and drop the store.
+     */
+    describeRetrieval(): RetrievalDescriptor;
     /**
      * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —
      * and if it DOES exist, compare what's there against this store's configuration instead of
@@ -550,6 +694,25 @@ declare class RedisVectorStore implements LexicalVectorStore {
      * document owns. The glob is escaped so `gone` does not reach into `goner#0`.
      */
     private chunkKeys;
+    /**
+     * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+     *
+     * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.
+     * Two reasons, and the second is the one that matters: the query language has no way to ask for
+     * "every chunk of this document" — `id` is the key name, not an indexed field — and `FT.SEARCH`
+     * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does
+     * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and
+     * {@link RedisVectorStore.updateMetadata} already use, so "the chunks this returns" and "the chunks
+     * a delete would take" cannot drift apart.
+     *
+     * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this
+     * is an inspection path (one document, on demand) and not something retrieval runs — but it is why
+     * this must not be put on a hot path or called in a loop over a corpus.
+     *
+     * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing
+     * a caller reading text back can do with it.
+     */
+    listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;
     listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
     /**
      * The id-only half of {@link RedisVectorStore.listDocuments}, served by `FT.SEARCH … NOCONTENT`:
@@ -653,6 +816,8 @@ declare class EmbeddingRetriever implements Retriever {
     private readonly store;
     private readonly options;
     constructor(embedder: EmbeddingProvider, store: VectorStore, options?: EmbeddingRetrieverOptions);
+    /** Telemetry self-description — the dense strategy, over whatever store it was handed. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -712,6 +877,12 @@ declare class KeywordRetriever implements Retriever {
     private readonly k1;
     private readonly b;
     constructor(options?: KeywordRetrieverOptions);
+    /**
+     * Telemetry self-description. No `store`: this retriever holds its own copy of the corpus in
+     * process, so attributing its retrievals to whichever vector store happens to hold the same chunks
+     * would credit a backend that was never queried.
+     */
+    describeRetrieval(): RetrievalDescriptor;
     /** How many chunks are currently indexed. */
     get size(): number;
     /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
@@ -757,6 +928,8 @@ declare class KeywordRetriever implements Retriever {
 declare class LexicalRetriever implements Retriever {
     private readonly store;
     constructor(store: LexicalVectorStore);
+    /** Telemetry self-description — the store's own lexical index, so the store is the same one. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -808,6 +981,8 @@ declare class HybridRetriever implements Retriever {
     private readonly retrievers;
     private readonly options;
     constructor(retrievers: Retriever[], options?: HybridRetrieverOptions);
+    /** Telemetry self-description — the store only when every leg agrees; see `describeSharedSource`. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -826,6 +1001,8 @@ declare class RerankingRetriever implements Retriever {
     private readonly reranker;
     private readonly options;
     constructor(base: Retriever, reranker: Reranker, options?: RerankingRetrieverOptions);
+    /** Telemetry self-description — the two-stage strategy, over the base's store. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -842,15 +1019,178 @@ declare class FilteredRetriever implements Retriever {
     private readonly base;
     private readonly filter;
     constructor(base: Retriever, filter: Record<string, unknown>);
+    /** Telemetry self-description — this scope, over the base's store. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
+/**
+ * Retrieval telemetry: one diagnostics event per retrieval, carrying how long it took, how much came
+ * back, how good it was, and what served it.
+ *
+ * Until this existed, retrieval reached Telescope only as the *tool call* that wrapped it (see
+ * `retrieval-tool.ts`), which says a retrieval happened and nothing else. The questions an operator
+ * actually arrives with — is retrieval slow, is it returning nothing, is one collection colder than
+ * the rest, did the scores collapse after a model swap — are all invisible in a tool-call row,
+ * because a tool call that returns zero passages and one that returns five perfect ones are the same
+ * row with the same `ok` status.
+ *
+ * ## One seam, not six
+ *
+ * Instrumentation is a WRAPPER over the core `Retriever` SPI ({@link instrumentRetriever}), not code
+ * inside each retriever. Every retriever in this package — and every retriever outside it — is the
+ * same one-method interface, so one wrapper covers all of them, including ones this package has
+ * never heard of. The alternative, an `emit` inside each of the six `retrieve` methods, would have
+ * had to be repeated in each, skipped by third-party retrievers entirely, and would have double- and
+ * triple-counted the composed ones (a hybrid over two legs emitting three events for one retrieval).
+ *
+ * ## How a composed retrieval reports
+ *
+ * **The outermost instrumented retriever in a call tree emits; anything instrumented inside it stays
+ * silent.** A retrieval is one question the caller asked, so it is one event no matter how many
+ * retrievers cooperated to answer it: `RerankingRetriever` over a `HybridRetriever` over a dense and
+ * a lexical leg is ONE retrieval, reported as `retriever: 'reranking'` with the duration of the
+ * whole thing and the scores the caller actually got back.
+ *
+ * The suppression is enforced with an {@link AsyncLocalStorage} flag rather than by asking hosts to
+ * wrap carefully, because the wrapping that double-counts is the natural one: a host that wraps its
+ * top-level retriever and *also* wraps the dense leg it shares with another code path has not made a
+ * mistake, and would otherwise get two events per retrieval, a zero-hit rate computed over a mixture
+ * of legs and composites, and a retrieval count roughly twice its query count.
+ *
+ * ## Opt-out safety, and what the hot path pays
+ *
+ * The event goes out on `aviary:rag:retrieval` via `@dudousxd/nestjs-diagnostics`, whose `emit` is
+ * gated on `channel.hasSubscribers` and never throws. This wrapper checks that same gate BEFORE it
+ * does anything at all — no clock read, no `AsyncLocalStorage.run`, no score arithmetic — and
+ * delegates straight through when nothing is listening. A host that wires this package without
+ * Telescope (or any subscriber) pays two `Map` lookups and a boolean per retrieval, and nothing else
+ * changes: the wrapper returns the base retriever's passages verbatim, and rethrows its errors
+ * unchanged.
+ *
+ * ## Why this channel is not merged into the typed `ChannelRegistry`
+ *
+ * `@dudousxd/nestjs-agent-rag-media` already emits `media.ingested`/`media.removed`/`media.skipped`/
+ * `media.failed` on the same `rag` lib, and flip's host app emits `rag:search` on it. Declaring
+ * `ChannelRegistry['rag'] = { retrieval: RagRetrievalEvent }` here would narrow `EventOf<'rag'>` to
+ * this one key process-wide and turn every one of those sibling emits into a compile error in any
+ * project that installs both packages. The payload stays typed where it matters — {@link emitRagRetrieval}
+ * takes {@link RagRetrievalEvent} — and the wire contract is documented below instead.
+ */
+/** The diagnostics lib segment. Shared with `@dudousxd/nestjs-agent-rag-media`'s `media.*` events. */
+declare const RAG_DIAGNOSTIC_LIB = "rag";
+/** The diagnostics event segment. */
+declare const RAG_RETRIEVAL_EVENT = "retrieval";
+/**
+ * The full channel name a subscriber listens on: `aviary:rag:retrieval`. This is the wire contract —
+ * `@dudousxd/nestjs-agent-telescope` subscribes to this exact string rather than importing this
+ * package, which is what keeps the telescope extension free of a dependency on the retrieval stack
+ * (and lets a host that uses neither still observe retrieval with a bare `diagnostics_channel`
+ * subscription).
+ */
+declare const RAG_RETRIEVAL_CHANNEL: string;
+/**
+ * The payload of one retrieval event. Counts, durations, kinds and scores only — never the query
+ * text and never passage text. Both are user content, and this lands in an ops store with a short
+ * retention window and a Slack-facing redaction budget; everything here is safe to put on a
+ * dashboard and is what tells the failure modes apart anyway.
+ *
+ * The DURATION is not in here: it rides the envelope (`emit`'s `opts.durationMs`), which is the field
+ * Telescope's OTel exporter turns into a latency histogram. Putting it in the payload instead would
+ * have made retrieval latency a number somebody reads out of a JSON blob rather than a graph.
+ */
+interface RagRetrievalEvent {
+    /** Which strategy answered — the OUTERMOST one, for a composed retriever. */
+    retriever: RetrieverKind;
+    /** Which backend held the chunks. Absent for an in-process retriever, or when legs disagree. */
+    store?: VectorStoreKind;
+    /** Store namespace (pg table / RediSearch index), or the host's logical collection. */
+    collection?: string;
+    /** What the caller asked for, so `chunks < topK` is readable as "the corpus ran out". */
+    topK: number;
+    /** How many passages came back. */
+    chunks: number;
+    /**
+     * `chunks === 0`. Carried as its own flag rather than left to be derived, because the zero-hit RATE
+     * is the headline number and deriving it means every consumer re-deriving the same predicate.
+     */
+    zeroHit: boolean;
+    /** Best score in the result, rounded to 4dp. Absent on a zero-hit. */
+    topScore?: number;
+    /** Mean score across the result, rounded to 4dp. Absent on a zero-hit. */
+    meanScore?: number;
+    /**
+     * The retrieval threw. Reported rather than dropped because a failed retrieval and an empty one
+     * look identical from the agent's side — both become "I couldn't find anything" — so a channel
+     * that only carried successes would go quiet exactly when retrieval broke.
+     */
+    failed: boolean;
+    /** The error message, when `failed`. */
+    error?: string;
+}
+/** Publish one retrieval event. `durationMs` rides the envelope; see {@link RagRetrievalEvent}. */
+declare function emitRagRetrieval(event: RagRetrievalEvent, durationMs: number): void;
+interface InstrumentRetrieverOptions {
+    /**
+     * Override the auto-detected {@link RetrievalDescriptor}, field by field. Needed for a retriever or
+     * store from outside this package (which reports `retriever: 'unknown'` and no store), and for a
+     * host that wants its own naming.
+     */
+    describe?: RetrievalDescriptor;
+    /**
+     * The logical collection this retrieval searched, when the store namespace is not it. Pass a
+     * function to read it off the call's metadata filter — the multi-tenant shape, where one index
+     * holds every collection and the filter picks one:
+     *
+     * ```ts
+     * instrumentRetriever(retriever, {
+     *   collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined),
+     * })
+     * ```
+     *
+     * Returning `undefined` falls back to the store namespace, which is the right answer for a query
+     * scoped to many collections at once: a breakdown panel needs ONE label per retrieval, and
+     * inventing a synthetic `"a+b+c"` bucket would produce a chart whose slices are combinations
+     * rather than collections.
+     */
+    collection?: string | ((filter: Record<string, unknown> | undefined) => string | undefined);
+}
+/**
+ * Wrap a retriever so every `retrieve` publishes a {@link RagRetrievalEvent} on
+ * {@link RAG_RETRIEVAL_CHANNEL}. Wrap the retriever you actually hand to the agent — the outermost
+ * one — and nothing else needs changing:
+ *
+ * ```ts
+ * const retriever = instrumentRetriever(
+ *   new HybridRetriever([new EmbeddingRetriever(embedder, store), new LexicalRetriever(store)]),
+ * );
+ * ```
+ *
+ * {@link createRetrievalTool} already does this for the tool it builds, so agentic retrieval is
+ * instrumented with no host change at all; call this directly for inject-mode retrieval
+ * (`AgentModule.forRoot({ retrieval })`) or for a host that calls `retrieve` itself. Wrapping twice
+ * is harmless — see the composed-retrieval section above.
+ */
+declare function instrumentRetriever(retriever: Retriever, options?: InstrumentRetrieverOptions): Retriever;
+
 interface RetrievalToolOptions {
     /** Tool name the model sees. Default `search_knowledge`. */
     name?: string;
     description?: string;
     /** Passages per search. Default lets the retriever decide (typically 5). */
     topK?: number;
+    /**
+     * Retrieval telemetry (`aviary:rag:retrieval` — duration, chunk count, score distribution, store
+     * and collection). **On by default**, because this tool is the once-per-retrieval seam in agentic
+     * mode: instrumenting here is what makes the RAG panels work for a host that only ever calls
+     * `createRetrievalTool`, with no wiring at all. It costs nothing when nobody subscribes (see
+     * {@link instrumentRetriever}), and cannot double-count when the host has already wrapped the
+     * retriever itself.
+     *
+     * Pass `false` to opt a single tool out — a host that reports retrieval its own way, or one whose
+     * corpus is small enough that the events are noise.
+     */
+    telemetry?: boolean | InstrumentRetrieverOptions;
 }
 /** A functional tool (`{ spec, handler }`) — pass it to nestjs `provideAgentTool`. */
 interface RetrievalTool {
@@ -862,10 +1202,14 @@ interface RetrievalTool {
  * decides it needs context. Its output `{ passages }` persists as the tool call's result, so sources
  * flow to the frontend and telescope through the normal tool-call machinery (the citation surface).
  *
+ * The retrieval ITSELF is also instrumented (`aviary:rag:retrieval`) unless `telemetry: false` — the
+ * tool-call row says a retrieval happened, the retrieval event says how long it took, how much came
+ * back and how good it was. See {@link instrumentRetriever}.
+ *
  * ```ts
  * providers: [provideAgentTool(createRetrievalTool(retriever))]
  * ```
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };
+export { type ChunkOptions, type ChunkRecord, type DescribesRetrieval, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_CHANNEL, RAG_RETRIEVAL_EVENT, type RagRetrievalEvent, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalDescriptor, type RetrievalTool, type RetrievalToolOptions, type RetrieverKind, type StoredChunk, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, documentIdOf, emitRagRetrieval, ingestChunks, ingestDocuments, instrumentRetriever, isLexicalVectorStore };