@dudousxd/nestjs-agent-telescope 0.7.1 → 0.8.0

package/dist/index.d.cts

@@ -1,14 +1,49 @@
 import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
-import { Watcher, WatcherContext, DashboardSpec, DataProvider } from '@dudousxd/nestjs-telescope';
+import { DataProvider, DashboardSection, Watcher, WatcherContext, DashboardSpec } from '@dudousxd/nestjs-telescope';
 import { GovernanceRange, ActorSpendRow, ModelSpendRow, PendingApprovalRow, RecentRunRow, ThreadActivityRow, ToolCallActivityRow, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, ThreadSpendRow, ToolStatRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
 
+interface AgentTelescopeExtensionOptions {
+    /** Deep-link template for a `{threadId}` cell, e.g. `'/admin/threads/{threadId}'`. */
+    threadHref?: string;
+    /** Deep-link template for a `{runId}` cell. Defaults to the in-app trace waterfall. */
+    runHref?: string;
+    /**
+     * HOST-contributed data providers, registered alongside the built-in ones.
+     *
+     * This exists because a panel on this dashboard **cannot** bind to a provider contributed by a
+     * different extension, and the reason is structural rather than a policy we could relax: the UI
+     * derives the request path from the dashboard id (`agent.overview` → `GET /ext/agent/data/:name`),
+     * and the controller 404s when `providerOwner(name) !== ext` so the URL namespace cannot be
+     * spoofed. A host that registers its own `TelescopeModule` extension therefore gets its own tab,
+     * never a panel on this one. Passing the providers through here makes THIS extension their owner,
+     * which is what makes a host section on this page resolve at all.
+     *
+     * Name them under your own prefix (`myapp.rag.collections`); anything starting with `agent.` is
+     * refused at boot, because a collision there would surface as Telescope's generic "contributed by
+     * both agent and agent" error, which names the same extension twice and says nothing useful.
+     */
+    providers?: DataProvider[];
+    /**
+     * HOST-contributed dashboard sections, appended after the built-in ones. Bind their panels to the
+     * providers passed above (or to any built-in `agent.*` provider).
+     *
+     * Size each section's panel count to an exact multiple of its `cols`, for the same reason every
+     * built-in section is: the renderer lays a section out as a fixed `grid-cols-N` grid with no
+     * `colSpan`, so an orphan panel leaves a visible hole beside it. That is a layout convention, not
+     * something validated here — a gap is cosmetic, and failing a host's boot over cosmetics would be
+     * a worse trade than the gap.
+     */
+    sections?: DashboardSection[];
+}
 /**
- * The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by two sources —
- * the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, and the
+ * The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by three sources —
+ * the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, the
  * authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage, run reliability,
- * tool activity, the approvals inbox) via the governance providers. The extension `name`,
- * entry-type id, dashboard id, and every provider name share the `agent` prefix so the registry's
- * global-uniqueness namespaces never collide with sibling extensions.
+ * tool activity, the approvals inbox) via the governance providers, and the `aviary:rag:retrieval`
+ * channel (retrieval latency, chunk counts, score distribution, store/collection) via the RAG
+ * watcher and providers. The extension `name`, entry-type ids, dashboard id, and every built-in
+ * provider name share the `agent` prefix so the registry's global-uniqueness namespaces never
+ * collide with sibling extensions.
  *
  * `threadHref` deep-links a table row's `threadId` cell out to the HOST's own thread viewer —
  * passed straight through to {@link agentDashboard}, mirroring `durableTelescopeExtension`'s
@@ -22,12 +57,11 @@ import { GovernanceRange, ActorSpendRow, ModelSpendRow, PendingApprovalRow, Rece
  * (e.g. `store-mikro-orm` / `store-drizzle` / `testing`) — in the same module that registers
  * `TelescopeModule.forRoot({ extensions: [agentTelescopeExtension()] })`. If the binding is
  * absent, those panels render an empty state; the live watcher-fed panels (Runs/Tokens stats and
- * the Tool-call status breakdown) keep working regardless.
+ * the Tool-call status breakdown) keep working regardless. The RAG panels need no binding at all —
+ * they read Telescope's own storage — but they stay empty until something emits retrieval telemetry
+ * (`createRetrievalTool` does by default; `instrumentRetriever` for every other call path).
  */
-declare function agentTelescopeExtension(opts?: {
-    threadHref?: string;
-    runHref?: string;
-}): _dudousxd_nestjs_telescope.TelescopeExtension;
+declare function agentTelescopeExtension(opts?: AgentTelescopeExtensionOptions): _dudousxd_nestjs_telescope.TelescopeExtension;
 
 /**
  * Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends
@@ -52,6 +86,39 @@ declare class AgentTelescopeWatcher implements Watcher {
     dispose(): void;
 }
 
+/** The Telescope entry `type` retrieval events are recorded as — see the class doc. */
+declare const RAG_ENTRY_TYPE = "agent-rag";
+/**
+ * Records `aviary:rag:retrieval` events as Telescope entries of type `agent-rag` — the source every
+ * RAG panel on the Agent dashboard reads.
+ *
+ * **Its own entry type, not `agent`.** Retrieval is per-tool-call where a run is per-conversation, so
+ * a busy hour produces an order of magnitude more retrieval events than agent events. Sharing the
+ * `agent` type would put them in one storage window: the providers page 5k entries of a type, and
+ * retrieval traffic would push `run.finished` out of that window, quietly zeroing the Runs and Tokens
+ * stats that have nothing to do with RAG. Separate types make the two independent, and give the
+ * Entries screen a "RAG" filter that lists retrievals and only retrievals.
+ *
+ * **The duration is lifted off the ENVELOPE into the entry content.** The emitter puts it there
+ * (`emit`'s `opts.durationMs`) because that is the field Telescope's OTel exporter turns into a
+ * latency histogram; the panels need it as an ordinary field they can bucket, and an entry's content
+ * is all a `DataProvider` gets. Recording it in both places would mean two sources of truth for the
+ * same number, so it is lifted rather than duplicated at the emitter.
+ *
+ * Claims `rag:retrieval` (refcounted, released in `dispose()`) so
+ * `@dudousxd/nestjs-diagnostics-telescope`'s generic bridge skips it instead of recording every
+ * retrieval a second time as a generic `diagnostic` entry.
+ *
+ * Registered by `agentTelescopeExtension()`; also usable on its own in a host's `watchers` list.
+ */
+declare class RagTelescopeWatcher implements Watcher {
+    readonly type = "agent-rag";
+    private readonly disposers;
+    register(ctx: WatcherContext): void;
+    /** Detach the subscription and release the diagnostics claim (e.g. on module destroy). */
+    dispose(): void;
+}
+
 /**
  * The "Agent" overview dashboard. Panels bind to the `agent.*` data providers.
  *
@@ -63,16 +130,156 @@ declare class AgentTelescopeWatcher implements Watcher {
  * still override it. Every table whose rows carry a `threadId`/`runId` gets a `Column.link` for it
  * (via {@link col}); `threadHref` left unset leaves that column plain text.
  *
- * Layout: six sections (Overview lean; Spend; Reliability; Activity; Approvals; Tools), each sized
- * so its panel count is an exact multiple of its `cols` — no half-empty row. `nestjs-telescope`'s
- * `ExtensionDashboardPage` renders a section as a `grid-cols-N` grid with one panel per cell and no
- * `colSpan`, so a lone table in an otherwise-empty row would leave a visible gap next to it.
+ * Layout: eight sections (Overview lean; Spend; Reliability; Activity; Approvals; Tools;
+ * Retrieval; Retrieval sources), each sized so its panel count is an exact multiple of its `cols` —
+ * no half-empty row. `nestjs-telescope`'s `ExtensionDashboardPage` renders a section as a
+ * `grid-cols-N` grid with one panel per cell and no `colSpan`, so a lone table in an otherwise-empty
+ * row would leave a visible gap next to it.
+ *
+ * `sections` appends HOST-contributed sections after the built-in ones — see
+ * {@link import('./agent-telescope.extension.js').agentTelescopeExtension}'s `sections`/`providers`
+ * options, which is the supported way an application puts its own panels (its knowledge-base
+ * collections, its ingestion activity) on this page. They are appended rather than interleaved so a
+ * host's layout can never push a built-in section out of the row it was sized for.
  */
 declare function agentDashboard(opts?: {
     threadHref?: string;
     runHref?: string;
+    sections?: DashboardSection[];
 }): DashboardSpec;
 
+/** One retrieval, normalized out of an entry's untyped `content`. */
+interface RagRetrieval {
+    at: Date;
+    retriever: string;
+    store: string | null;
+    collection: string | null;
+    chunks: number;
+    zeroHit: boolean;
+    topScore: number | null;
+    durationMs: number | null;
+    failed: boolean;
+}
+interface BreakdownSegment$1 {
+    label: string;
+    value: number;
+}
+interface DistributionBucket {
+    label: string;
+    count: number;
+}
+/** One row of the per-collection table. */
+interface CollectionRow {
+    collection: string;
+    store: string;
+    retrievals: number;
+    zeroHits: number;
+    p95Ms: number | string;
+    meanTopScore: number | string;
+}
+/** One row of the slowest-retrievals table. */
+interface SlowestRow {
+    at: string;
+    retriever: string;
+    store: string;
+    collection: string;
+    chunks: number;
+    topScore: number | string;
+    durationMs: number | string;
+}
+/**
+ * Normalize one storage entry into a {@link RagRetrieval}, or `null` when it is not a retrieval this
+ * shaping understands. Field-by-field `typeof` checks rather than a cast: entries are persisted JSON
+ * written by a possibly older producer, so "the field is there and is a number" is a runtime
+ * question, and a missing `durationMs` must land as `null` (excluded from percentiles) rather than as
+ * a `NaN` that silently poisons every aggregate it touches.
+ */
+declare function toRagRetrieval(entry: unknown): RagRetrieval | null;
+/**
+ * Every retrieval in the window, newest first. Takes the resolved binding as `unknown` and narrows it
+ * here, so a host whose Telescope storage is missing or unrecognised gets empty panels rather than a
+ * 502 on every RAG card — the same degrade-don't-throw posture the governance providers take.
+ */
+declare function readRetrievals(storage: unknown): Promise<RagRetrieval[]>;
+/** Nearest-rank percentile over an unsorted sample. `null` for an empty sample. */
+declare function percentile(samples: number[], fraction: number): number | null;
+/** Fraction (0–1) of retrievals that came back with nothing. `0` over an empty window. */
+declare function zeroHitRate(retrievals: RagRetrieval[]): number;
+/** Mean passages returned per retrieval — `topK` minus this is how often the corpus ran out. */
+declare function meanChunks(retrievals: RagRetrieval[]): number;
+/** Latency histogram over the ladder above, plus p50/p95/p99 of the raw samples. */
+declare function toLatencyDistribution(retrievals: RagRetrieval[]): {
+    buckets: DistributionBucket[];
+    p50?: number;
+    p95?: number;
+    p99?: number;
+};
+/**
+ * Top-score histogram — **for ONE retriever kind at a time**, which is the whole reason this takes a
+ * `retriever` argument instead of bucketing everything it was handed.
+ *
+ * A `Passage.score` has no shared meaning across strategies: `EmbeddingRetriever` returns a
+ * calibrated cosine similarity in `[0, 1]`, a BM25 leg returns an unbounded relevance score in the
+ * tens, and `HybridRetriever`'s RRF returns a rank-derived number that lives in a band about one
+ * part in fifty wide and says nothing about quality at all (see the score section on
+ * `HybridRetriever`). Pouring those into one histogram produces a chart where the bins mean a
+ * different thing per bar — and the reading it invites, "our scores collapsed", would be a change in
+ * traffic MIX rather than in retrieval quality.
+ *
+ * So the panel binds `query.retriever: 'embedding'`: the dense leg is the only population whose
+ * score is comparable across queries, which is also why `minScore` lives on that retriever alone.
+ * Scores outside `[0, 1]` are clamped into the end bins rather than dropped, so a store that reports
+ * a distance-derived score still shows up as an obviously-pinned bar instead of an empty chart.
+ */
+declare function toScoreDistribution(retrievals: RagRetrieval[], retriever: string): {
+    buckets: DistributionBucket[];
+    p50?: number;
+    p95?: number;
+};
+/**
+ * Retrievals and zero-hits per UTC hour, oldest bucket first, over the last {@link TREND_HOURS}.
+ * Empty hours are emitted as zeroes so a quiet stretch reads as a gap in the line rather than
+ * disappearing and making the outage look like it never happened.
+ */
+declare function toRetrievalTrendRows(retrievals: RagRetrieval[], now?: Date): Array<{
+    label: string;
+    retrievals: number;
+    zeroHits: number;
+}>;
+/** Retrievals by vector store (`memory`/`pg`/`redis`, or `—` for an in-process retriever). */
+declare function toStoreSegments(retrievals: RagRetrieval[]): BreakdownSegment$1[];
+/** Retrievals by strategy — the composed kind, since that is what answered. */
+declare function toRetrieverSegments(retrievals: RagRetrieval[]): BreakdownSegment$1[];
+/** Per-collection rollup, busiest first. `p95Ms`/`meanTopScore` fall back to `—` when unmeasured. */
+declare function toCollectionRows(retrievals: RagRetrieval[], limit?: number): CollectionRow[];
+/**
+ * The slowest retrievals in the window, worst first — the table an operator opens after the p95
+ * moves. Sorted by duration rather than by recency on purpose: "recent retrievals" would be a list
+ * of whatever just happened, which the trend already shows in aggregate, whereas the tail is the
+ * only place a single pathological query is visible at all.
+ */
+declare function toSlowestRows(retrievals: RagRetrieval[], limit?: number): SlowestRow[];
+/** stat → retrievals in the window. */
+declare function ragRetrievalsProvider(): DataProvider;
+/** stat (percent) → share of retrievals that returned nothing. */
+declare function ragZeroHitRateProvider(): DataProvider;
+/** stat → mean passages returned per retrieval. */
+declare function ragChunksProvider(): DataProvider;
+/** distribution → retrieval latency, with p50/p95/p99 markers. */
+declare function ragLatencyProvider(): DataProvider;
+/** distribution → top score for ONE retriever kind (`query.retriever`, default `embedding`). */
+declare function ragScoresProvider(): DataProvider;
+/** timeseries → retrievals and zero-hits per hour. */
+declare function ragTrendProvider(): DataProvider;
+/** breakdown → retrievals by vector store. */
+declare function ragStoreBreakdownProvider(): DataProvider;
+/** breakdown → retrievals by retriever strategy. */
+declare function ragRetrieverBreakdownProvider(): DataProvider;
+/** table → per-collection rollup, busiest first. */
+declare function ragCollectionsTableProvider(): DataProvider;
+/** table → the slowest retrievals in the window. */
+declare function ragSlowestTableProvider(): DataProvider;
+
 /** stat → total agent runs (run.finished entries). */
 declare function agentRunsProvider(): DataProvider;
 /** stat → total tokens across all finished runs. */
@@ -296,4 +503,4 @@ declare function agentPendingApprovalsTableProvider(): DataProvider;
 /** table → per-tool call/failure/rejection/latency rollup over the range. */
 declare function agentToolStatsTableProvider(): DataProvider;
 
-export { AgentTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentPendingApprovalsCountProvider, agentPendingApprovalsTableProvider, agentRecentRunsTableProvider, agentRecentThreadsTableProvider, agentRecentToolCallsTableProvider, agentRunErrorsProvider, agentRunsByAgentTableProvider, agentRunsDurationProvider, agentRunsFailedProvider, agentRunsProvider, agentRunsRetriesProvider, agentRunsSuccessRateProvider, agentRunsTotalProvider, agentRunsTrendProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatsTableProvider, agentToolStatusProvider, agentToolsProvider, agentTopThreadsTableProvider, agentUsageTrendProvider, capErrorMessage, resolveRange, shiftUtcDay, shortPromptHash, toActorSpendRows, toActorSpendSegments, toModelSpendRows, toModelSpendSegments, toPendingApprovalTableRows, toRecentRunTableRows, toRecentThreadTableRows, toRecentToolCallRows, toRunAgentTableRows, toRunErrorSegments, toRunTrendRows, toThreadSpendRows, toToolStatTableRows, toUsageTrendRows, totalCostUsd, totalTokens };
+export { type AgentTelescopeExtensionOptions, AgentTelescopeWatcher, RAG_ENTRY_TYPE, type RagRetrieval, RagTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentPendingApprovalsCountProvider, agentPendingApprovalsTableProvider, agentRecentRunsTableProvider, agentRecentThreadsTableProvider, agentRecentToolCallsTableProvider, agentRunErrorsProvider, agentRunsByAgentTableProvider, agentRunsDurationProvider, agentRunsFailedProvider, agentRunsProvider, agentRunsRetriesProvider, agentRunsSuccessRateProvider, agentRunsTotalProvider, agentRunsTrendProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatsTableProvider, agentToolStatusProvider, agentToolsProvider, agentTopThreadsTableProvider, agentUsageTrendProvider, capErrorMessage, meanChunks, percentile, ragChunksProvider, ragCollectionsTableProvider, ragLatencyProvider, ragRetrievalsProvider, ragRetrieverBreakdownProvider, ragScoresProvider, ragSlowestTableProvider, ragStoreBreakdownProvider, ragTrendProvider, ragZeroHitRateProvider, readRetrievals, resolveRange, shiftUtcDay, shortPromptHash, toActorSpendRows, toActorSpendSegments, toCollectionRows, toLatencyDistribution, toModelSpendRows, toModelSpendSegments, toPendingApprovalTableRows, toRagRetrieval, toRecentRunTableRows, toRecentThreadTableRows, toRecentToolCallRows, toRetrievalTrendRows, toRetrieverSegments, toRunAgentTableRows, toRunErrorSegments, toRunTrendRows, toScoreDistribution, toSlowestRows, toStoreSegments, toThreadSpendRows, toToolStatTableRows, toUsageTrendRows, totalCostUsd, totalTokens, zeroHitRate };

package/dist/index.d.ts

@@ -1,14 +1,49 @@
 import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
-import { Watcher, WatcherContext, DashboardSpec, DataProvider } from '@dudousxd/nestjs-telescope';
+import { DataProvider, DashboardSection, Watcher, WatcherContext, DashboardSpec } from '@dudousxd/nestjs-telescope';
 import { GovernanceRange, ActorSpendRow, ModelSpendRow, PendingApprovalRow, RecentRunRow, ThreadActivityRow, ToolCallActivityRow, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, ThreadSpendRow, ToolStatRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
 
+interface AgentTelescopeExtensionOptions {
+    /** Deep-link template for a `{threadId}` cell, e.g. `'/admin/threads/{threadId}'`. */
+    threadHref?: string;
+    /** Deep-link template for a `{runId}` cell. Defaults to the in-app trace waterfall. */
+    runHref?: string;
+    /**
+     * HOST-contributed data providers, registered alongside the built-in ones.
+     *
+     * This exists because a panel on this dashboard **cannot** bind to a provider contributed by a
+     * different extension, and the reason is structural rather than a policy we could relax: the UI
+     * derives the request path from the dashboard id (`agent.overview` → `GET /ext/agent/data/:name`),
+     * and the controller 404s when `providerOwner(name) !== ext` so the URL namespace cannot be
+     * spoofed. A host that registers its own `TelescopeModule` extension therefore gets its own tab,
+     * never a panel on this one. Passing the providers through here makes THIS extension their owner,
+     * which is what makes a host section on this page resolve at all.
+     *
+     * Name them under your own prefix (`myapp.rag.collections`); anything starting with `agent.` is
+     * refused at boot, because a collision there would surface as Telescope's generic "contributed by
+     * both agent and agent" error, which names the same extension twice and says nothing useful.
+     */
+    providers?: DataProvider[];
+    /**
+     * HOST-contributed dashboard sections, appended after the built-in ones. Bind their panels to the
+     * providers passed above (or to any built-in `agent.*` provider).
+     *
+     * Size each section's panel count to an exact multiple of its `cols`, for the same reason every
+     * built-in section is: the renderer lays a section out as a fixed `grid-cols-N` grid with no
+     * `colSpan`, so an orphan panel leaves a visible hole beside it. That is a layout convention, not
+     * something validated here — a gap is cosmetic, and failing a host's boot over cosmetics would be
+     * a worse trade than the gap.
+     */
+    sections?: DashboardSection[];
+}
 /**
- * The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by two sources —
- * the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, and the
+ * The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by three sources —
+ * the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, the
  * authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage, run reliability,
- * tool activity, the approvals inbox) via the governance providers. The extension `name`,
- * entry-type id, dashboard id, and every provider name share the `agent` prefix so the registry's
- * global-uniqueness namespaces never collide with sibling extensions.
+ * tool activity, the approvals inbox) via the governance providers, and the `aviary:rag:retrieval`
+ * channel (retrieval latency, chunk counts, score distribution, store/collection) via the RAG
+ * watcher and providers. The extension `name`, entry-type ids, dashboard id, and every built-in
+ * provider name share the `agent` prefix so the registry's global-uniqueness namespaces never
+ * collide with sibling extensions.
  *
  * `threadHref` deep-links a table row's `threadId` cell out to the HOST's own thread viewer —
  * passed straight through to {@link agentDashboard}, mirroring `durableTelescopeExtension`'s
@@ -22,12 +57,11 @@ import { GovernanceRange, ActorSpendRow, ModelSpendRow, PendingApprovalRow, Rece
  * (e.g. `store-mikro-orm` / `store-drizzle` / `testing`) — in the same module that registers
  * `TelescopeModule.forRoot({ extensions: [agentTelescopeExtension()] })`. If the binding is
  * absent, those panels render an empty state; the live watcher-fed panels (Runs/Tokens stats and
- * the Tool-call status breakdown) keep working regardless.
+ * the Tool-call status breakdown) keep working regardless. The RAG panels need no binding at all —
+ * they read Telescope's own storage — but they stay empty until something emits retrieval telemetry
+ * (`createRetrievalTool` does by default; `instrumentRetriever` for every other call path).
  */
-declare function agentTelescopeExtension(opts?: {
-    threadHref?: string;
-    runHref?: string;
-}): _dudousxd_nestjs_telescope.TelescopeExtension;
+declare function agentTelescopeExtension(opts?: AgentTelescopeExtensionOptions): _dudousxd_nestjs_telescope.TelescopeExtension;
 
 /**
  * Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends
@@ -52,6 +86,39 @@ declare class AgentTelescopeWatcher implements Watcher {
     dispose(): void;
 }
 
+/** The Telescope entry `type` retrieval events are recorded as — see the class doc. */
+declare const RAG_ENTRY_TYPE = "agent-rag";
+/**
+ * Records `aviary:rag:retrieval` events as Telescope entries of type `agent-rag` — the source every
+ * RAG panel on the Agent dashboard reads.
+ *
+ * **Its own entry type, not `agent`.** Retrieval is per-tool-call where a run is per-conversation, so
+ * a busy hour produces an order of magnitude more retrieval events than agent events. Sharing the
+ * `agent` type would put them in one storage window: the providers page 5k entries of a type, and
+ * retrieval traffic would push `run.finished` out of that window, quietly zeroing the Runs and Tokens
+ * stats that have nothing to do with RAG. Separate types make the two independent, and give the
+ * Entries screen a "RAG" filter that lists retrievals and only retrievals.
+ *
+ * **The duration is lifted off the ENVELOPE into the entry content.** The emitter puts it there
+ * (`emit`'s `opts.durationMs`) because that is the field Telescope's OTel exporter turns into a
+ * latency histogram; the panels need it as an ordinary field they can bucket, and an entry's content
+ * is all a `DataProvider` gets. Recording it in both places would mean two sources of truth for the
+ * same number, so it is lifted rather than duplicated at the emitter.
+ *
+ * Claims `rag:retrieval` (refcounted, released in `dispose()`) so
+ * `@dudousxd/nestjs-diagnostics-telescope`'s generic bridge skips it instead of recording every
+ * retrieval a second time as a generic `diagnostic` entry.
+ *
+ * Registered by `agentTelescopeExtension()`; also usable on its own in a host's `watchers` list.
+ */
+declare class RagTelescopeWatcher implements Watcher {
+    readonly type = "agent-rag";
+    private readonly disposers;
+    register(ctx: WatcherContext): void;
+    /** Detach the subscription and release the diagnostics claim (e.g. on module destroy). */
+    dispose(): void;
+}
+
 /**
  * The "Agent" overview dashboard. Panels bind to the `agent.*` data providers.
  *
@@ -63,16 +130,156 @@ declare class AgentTelescopeWatcher implements Watcher {
  * still override it. Every table whose rows carry a `threadId`/`runId` gets a `Column.link` for it
  * (via {@link col}); `threadHref` left unset leaves that column plain text.
  *
- * Layout: six sections (Overview lean; Spend; Reliability; Activity; Approvals; Tools), each sized
- * so its panel count is an exact multiple of its `cols` — no half-empty row. `nestjs-telescope`'s
- * `ExtensionDashboardPage` renders a section as a `grid-cols-N` grid with one panel per cell and no
- * `colSpan`, so a lone table in an otherwise-empty row would leave a visible gap next to it.
+ * Layout: eight sections (Overview lean; Spend; Reliability; Activity; Approvals; Tools;
+ * Retrieval; Retrieval sources), each sized so its panel count is an exact multiple of its `cols` —
+ * no half-empty row. `nestjs-telescope`'s `ExtensionDashboardPage` renders a section as a
+ * `grid-cols-N` grid with one panel per cell and no `colSpan`, so a lone table in an otherwise-empty
+ * row would leave a visible gap next to it.
+ *
+ * `sections` appends HOST-contributed sections after the built-in ones — see
+ * {@link import('./agent-telescope.extension.js').agentTelescopeExtension}'s `sections`/`providers`
+ * options, which is the supported way an application puts its own panels (its knowledge-base
+ * collections, its ingestion activity) on this page. They are appended rather than interleaved so a
+ * host's layout can never push a built-in section out of the row it was sized for.
  */
 declare function agentDashboard(opts?: {
     threadHref?: string;
     runHref?: string;
+    sections?: DashboardSection[];
 }): DashboardSpec;
 
+/** One retrieval, normalized out of an entry's untyped `content`. */
+interface RagRetrieval {
+    at: Date;
+    retriever: string;
+    store: string | null;
+    collection: string | null;
+    chunks: number;
+    zeroHit: boolean;
+    topScore: number | null;
+    durationMs: number | null;
+    failed: boolean;
+}
+interface BreakdownSegment$1 {
+    label: string;
+    value: number;
+}
+interface DistributionBucket {
+    label: string;
+    count: number;
+}
+/** One row of the per-collection table. */
+interface CollectionRow {
+    collection: string;
+    store: string;
+    retrievals: number;
+    zeroHits: number;
+    p95Ms: number | string;
+    meanTopScore: number | string;
+}
+/** One row of the slowest-retrievals table. */
+interface SlowestRow {
+    at: string;
+    retriever: string;
+    store: string;
+    collection: string;
+    chunks: number;
+    topScore: number | string;
+    durationMs: number | string;
+}
+/**
+ * Normalize one storage entry into a {@link RagRetrieval}, or `null` when it is not a retrieval this
+ * shaping understands. Field-by-field `typeof` checks rather than a cast: entries are persisted JSON
+ * written by a possibly older producer, so "the field is there and is a number" is a runtime
+ * question, and a missing `durationMs` must land as `null` (excluded from percentiles) rather than as
+ * a `NaN` that silently poisons every aggregate it touches.
+ */
+declare function toRagRetrieval(entry: unknown): RagRetrieval | null;
+/**
+ * Every retrieval in the window, newest first. Takes the resolved binding as `unknown` and narrows it
+ * here, so a host whose Telescope storage is missing or unrecognised gets empty panels rather than a
+ * 502 on every RAG card — the same degrade-don't-throw posture the governance providers take.
+ */
+declare function readRetrievals(storage: unknown): Promise<RagRetrieval[]>;
+/** Nearest-rank percentile over an unsorted sample. `null` for an empty sample. */
+declare function percentile(samples: number[], fraction: number): number | null;
+/** Fraction (0–1) of retrievals that came back with nothing. `0` over an empty window. */
+declare function zeroHitRate(retrievals: RagRetrieval[]): number;
+/** Mean passages returned per retrieval — `topK` minus this is how often the corpus ran out. */
+declare function meanChunks(retrievals: RagRetrieval[]): number;
+/** Latency histogram over the ladder above, plus p50/p95/p99 of the raw samples. */
+declare function toLatencyDistribution(retrievals: RagRetrieval[]): {
+    buckets: DistributionBucket[];
+    p50?: number;
+    p95?: number;
+    p99?: number;
+};
+/**
+ * Top-score histogram — **for ONE retriever kind at a time**, which is the whole reason this takes a
+ * `retriever` argument instead of bucketing everything it was handed.
+ *
+ * A `Passage.score` has no shared meaning across strategies: `EmbeddingRetriever` returns a
+ * calibrated cosine similarity in `[0, 1]`, a BM25 leg returns an unbounded relevance score in the
+ * tens, and `HybridRetriever`'s RRF returns a rank-derived number that lives in a band about one
+ * part in fifty wide and says nothing about quality at all (see the score section on
+ * `HybridRetriever`). Pouring those into one histogram produces a chart where the bins mean a
+ * different thing per bar — and the reading it invites, "our scores collapsed", would be a change in
+ * traffic MIX rather than in retrieval quality.
+ *
+ * So the panel binds `query.retriever: 'embedding'`: the dense leg is the only population whose
+ * score is comparable across queries, which is also why `minScore` lives on that retriever alone.
+ * Scores outside `[0, 1]` are clamped into the end bins rather than dropped, so a store that reports
+ * a distance-derived score still shows up as an obviously-pinned bar instead of an empty chart.
+ */
+declare function toScoreDistribution(retrievals: RagRetrieval[], retriever: string): {
+    buckets: DistributionBucket[];
+    p50?: number;
+    p95?: number;
+};
+/**
+ * Retrievals and zero-hits per UTC hour, oldest bucket first, over the last {@link TREND_HOURS}.
+ * Empty hours are emitted as zeroes so a quiet stretch reads as a gap in the line rather than
+ * disappearing and making the outage look like it never happened.
+ */
+declare function toRetrievalTrendRows(retrievals: RagRetrieval[], now?: Date): Array<{
+    label: string;
+    retrievals: number;
+    zeroHits: number;
+}>;
+/** Retrievals by vector store (`memory`/`pg`/`redis`, or `—` for an in-process retriever). */
+declare function toStoreSegments(retrievals: RagRetrieval[]): BreakdownSegment$1[];
+/** Retrievals by strategy — the composed kind, since that is what answered. */
+declare function toRetrieverSegments(retrievals: RagRetrieval[]): BreakdownSegment$1[];
+/** Per-collection rollup, busiest first. `p95Ms`/`meanTopScore` fall back to `—` when unmeasured. */
+declare function toCollectionRows(retrievals: RagRetrieval[], limit?: number): CollectionRow[];
+/**
+ * The slowest retrievals in the window, worst first — the table an operator opens after the p95
+ * moves. Sorted by duration rather than by recency on purpose: "recent retrievals" would be a list
+ * of whatever just happened, which the trend already shows in aggregate, whereas the tail is the
+ * only place a single pathological query is visible at all.
+ */
+declare function toSlowestRows(retrievals: RagRetrieval[], limit?: number): SlowestRow[];
+/** stat → retrievals in the window. */
+declare function ragRetrievalsProvider(): DataProvider;
+/** stat (percent) → share of retrievals that returned nothing. */
+declare function ragZeroHitRateProvider(): DataProvider;
+/** stat → mean passages returned per retrieval. */
+declare function ragChunksProvider(): DataProvider;
+/** distribution → retrieval latency, with p50/p95/p99 markers. */
+declare function ragLatencyProvider(): DataProvider;
+/** distribution → top score for ONE retriever kind (`query.retriever`, default `embedding`). */
+declare function ragScoresProvider(): DataProvider;
+/** timeseries → retrievals and zero-hits per hour. */
+declare function ragTrendProvider(): DataProvider;
+/** breakdown → retrievals by vector store. */
+declare function ragStoreBreakdownProvider(): DataProvider;
+/** breakdown → retrievals by retriever strategy. */
+declare function ragRetrieverBreakdownProvider(): DataProvider;
+/** table → per-collection rollup, busiest first. */
+declare function ragCollectionsTableProvider(): DataProvider;
+/** table → the slowest retrievals in the window. */
+declare function ragSlowestTableProvider(): DataProvider;
+
 /** stat → total agent runs (run.finished entries). */
 declare function agentRunsProvider(): DataProvider;
 /** stat → total tokens across all finished runs. */
@@ -296,4 +503,4 @@ declare function agentPendingApprovalsTableProvider(): DataProvider;
 /** table → per-tool call/failure/rejection/latency rollup over the range. */
 declare function agentToolStatsTableProvider(): DataProvider;
 
-export { AgentTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentPendingApprovalsCountProvider, agentPendingApprovalsTableProvider, agentRecentRunsTableProvider, agentRecentThreadsTableProvider, agentRecentToolCallsTableProvider, agentRunErrorsProvider, agentRunsByAgentTableProvider, agentRunsDurationProvider, agentRunsFailedProvider, agentRunsProvider, agentRunsRetriesProvider, agentRunsSuccessRateProvider, agentRunsTotalProvider, agentRunsTrendProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatsTableProvider, agentToolStatusProvider, agentToolsProvider, agentTopThreadsTableProvider, agentUsageTrendProvider, capErrorMessage, resolveRange, shiftUtcDay, shortPromptHash, toActorSpendRows, toActorSpendSegments, toModelSpendRows, toModelSpendSegments, toPendingApprovalTableRows, toRecentRunTableRows, toRecentThreadTableRows, toRecentToolCallRows, toRunAgentTableRows, toRunErrorSegments, toRunTrendRows, toThreadSpendRows, toToolStatTableRows, toUsageTrendRows, totalCostUsd, totalTokens };
+export { type AgentTelescopeExtensionOptions, AgentTelescopeWatcher, RAG_ENTRY_TYPE, type RagRetrieval, RagTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentPendingApprovalsCountProvider, agentPendingApprovalsTableProvider, agentRecentRunsTableProvider, agentRecentThreadsTableProvider, agentRecentToolCallsTableProvider, agentRunErrorsProvider, agentRunsByAgentTableProvider, agentRunsDurationProvider, agentRunsFailedProvider, agentRunsProvider, agentRunsRetriesProvider, agentRunsSuccessRateProvider, agentRunsTotalProvider, agentRunsTrendProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatsTableProvider, agentToolStatusProvider, agentToolsProvider, agentTopThreadsTableProvider, agentUsageTrendProvider, capErrorMessage, meanChunks, percentile, ragChunksProvider, ragCollectionsTableProvider, ragLatencyProvider, ragRetrievalsProvider, ragRetrieverBreakdownProvider, ragScoresProvider, ragSlowestTableProvider, ragStoreBreakdownProvider, ragTrendProvider, ragZeroHitRateProvider, readRetrievals, resolveRange, shiftUtcDay, shortPromptHash, toActorSpendRows, toActorSpendSegments, toCollectionRows, toLatencyDistribution, toModelSpendRows, toModelSpendSegments, toPendingApprovalTableRows, toRagRetrieval, toRecentRunTableRows, toRecentThreadTableRows, toRecentToolCallRows, toRetrievalTrendRows, toRetrieverSegments, toRunAgentTableRows, toRunErrorSegments, toRunTrendRows, toScoreDistribution, toSlowestRows, toStoreSegments, toThreadSpendRows, toToolStatTableRows, toUsageTrendRows, totalCostUsd, totalTokens, zeroHitRate };