@dudousxd/nestjs-agent-telescope

The first-class @dudousxd/nestjs-telescope extension for nestjs-agent. It adds an "Agent" tab fed by three sources: the aviary:agent:* diagnostics channel (live runs, tool calls) via a watcher, the AGENT_GOVERNANCE_QUERIES read-model (historical spend/usage, run reliability, tool stats, the approvals inbox, and paginated runs/tool-calls/threads tables) via a set of dashboard data providers, and the aviary:rag:retrieval channel (retrieval latency, passage counts, scores, store/collection) via a second watcher — see RAG retrieval. Run detail also correlates into the TRACES tab (see Tracing below).

pnpm add @dudousxd/nestjs-agent-telescope @dudousxd/nestjs-telescope

Minimal exampleCopy Anchor Link

Register agentTelescopeExtension() on Telescope's extensions array, same as any other Telescope extension:

import { TelescopeModule } from '@dudousxd/nestjs-telescope';
import { agentTelescopeExtension } from '@dudousxd/nestjs-agent-telescope';

@Module({
  imports: [
    TelescopeModule.forRoot({
      authorizer: () => true, // restrict in production
      extensions: [agentTelescopeExtension()],
    }),
  ],
})
export class AppModule {}

OptionsCopy Anchor Link

ExportsCopy Anchor Link

TracingCopy Anchor Link

Every agent run also emits diagnostics spans — llm.turn, tool.execution, retrieval, follow-ups (core's AGENT_SPAN_EVENTS) — correlated by traceId = runId. With a span-aware bridge these render in Telescope's TRACES tab as a nested waterfall for the run: one row per model call, tool execution, RAG retrieval, or follow-up-suggestions call, each with its duration and, on failure, an error phase. Span payloads are metadata-only (model id, token counts, tool name/type, step index) — never prompt or output text — and are emitted from inside the checkpointed step bodies, so a replayed (cached) step never re-emits its span.

Rendering requires:

• @dudousxd/nestjs-agent-core >=0.7.0 (emits the spans; already satisfied by this package's own dependency on it).
• @dudousxd/nestjs-diagnostics-telescope >=0.7 — the span-aware diagnostics bridge that turns :start/:end/:asyncStart/:asyncEnd/:error sub-channel traffic into Telescope spans.
• @dudousxd/nestjs-telescope >=1.17 — the version that added explicit RecordInput.traceId support.

Without both bridge versions the spans are still emitted (cheaply — the phase envelopes are gated on subscriber presence) but simply go unobserved; nothing breaks. Once wired, a run/thread table's runId cell defaults to a #/traces/{runId} deep link into that waterfall (override via agentTelescopeExtension({ runHref }) if the host has its own run viewer).

RAG retrievalCopy Anchor Link

The Retrieval and Retrieval sources sections (retrieval count, zero-hit rate, passages per retrieval, latency, top dense score, trend, breakdowns by store / retriever / collection, slowest retrievals) read agent-rag entries from Telescope's own storage — no DI binding needed. They stay empty until something publishes retrieval telemetry: createRetrievalTool from -rag does so by default; wrap any other retriever (e.g. inject-mode AgentModule.forRoot({ retrieval })) with instrumentRetriever(retriever). Retrievals use their own entry type so high-volume retrieval traffic can't push agent entries out of the providers' window. The watcher claims rag:retrieval, so the generic diagnostics bridge doesn't double-record it.

Peer dependenciesCopy Anchor Link

@dudousxd/nestjs-telescope (>=1.18.0).

When to use itCopy Anchor Link

Add this package once you're already running @dudousxd/nestjs-telescope and want agent runs, tool calls, and spend in the same console as your requests, queries, and jobs — no separate route to stand up. If you don't run Telescope, @dudousxd/nestjs-agent-dashboard gives you the same governance surfaces standalone (see Cost & Governance).

RelatedCopy Anchor Link

• Cost & Governance — the ledger, the read-model, and surfacing it via dashboard or Telescope tab
• Telescope docs — the extension mechanism, watchers, and the console itself