@dudousxd/nestjs-agent-telescope

The first-class @dudousxd/nestjs-telescope extension for nestjs-agent. It adds an "Agent" tab fed by two sources: the aviary:agent:* diagnostics channel (live runs, tool calls) via a watcher, and 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. Run detail also correlates into the TRACES tab (see Tracing below).

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

npm install @dudousxd/nestjs-agent-telescope @dudousxd/nestjs-telescope

Minimal example

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 {}

Exports

Tracing

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 peer).
• @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).

Peer dependencies

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

When to use it

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).

Related

• 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