@dudousxd/nestjs-agent-telescope 0.3.5 → 0.5.0

package/dist/index.d.ts

@@ -1,39 +1,89 @@
 import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
 import { Watcher, WatcherContext, DashboardSpec, DataProvider } from '@dudousxd/nestjs-telescope';
-import { GovernanceRange, ActorSpendRow, ModelSpendRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
+import { GovernanceRange, ActorSpendRow, ModelSpendRow, PendingApprovalRow, RecentRunRow, ThreadActivityRow, ToolCallActivityRow, RunAgentBreakdownRow, RunErrorBreakdownRow, RunTrendPoint, ThreadSpendRow, ToolStatRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
 
 /**
  * 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
- * authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage) 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.
+ * 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.
  *
- * Host wiring: the governance (Spend/Models/Actors) panels resolve `AGENT_GOVERNANCE_QUERIES` from
- * the host DI container at request time (via `ctx.moduleRef`). The host must bind that token — from
- * its store adapter (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 keep working regardless.
+ * `threadHref`/`runHref` deep-link a table row's `threadId`/`runId` cell out to the host's own
+ * thread/run viewer — passed straight through to {@link agentDashboard}, mirroring
+ * `durableTelescopeExtension`'s `runHref` option.
+ *
+ * Host wiring: the governance panels (Spend/Models/Actors/Reliability/Runs/Threads/Approvals/Tool
+ * stats/Recent tool calls) resolve `AGENT_GOVERNANCE_QUERIES` from the host DI container at
+ * request time (via `ctx.moduleRef`). The host must bind that token — from its store adapter
+ * (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.
  */
-declare function agentTelescopeExtension(): _dudousxd_nestjs_telescope.TelescopeExtension;
+declare function agentTelescopeExtension(opts?: {
+    threadHref?: string;
+    runHref?: string;
+}): _dudousxd_nestjs_telescope.TelescopeExtension;
 
 /**
  * Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends
  * only on the diagnostics channel — not on the agent runtime — so it stays fully decoupled.
+ *
+ * Iterates {@link AGENT_DIAGNOSTIC_EVENTS} (all 8 point events on `ChannelRegistry['agent']`)
+ * rather than a hand-written literal, so `run.failed`/`delegated`/`retrieved` are recorded and
+ * tagged — filterable in the Telescope UI — like every other agent event.
+ *
+ * Coexists with `@dudousxd/nestjs-diagnostics-telescope`'s generic watcher: `register()` CLAIMS
+ * every recorded key via `claimDiagnostics('agent', ...)` (diagnostics 0.7+), so the generic
+ * bridge skips them at record time instead of duplicating each event as a `diagnostic` entry —
+ * no `exclude` wiring needed anymore. `dispose()` releases the claim.
+ *
+ * Register it with the telescope module's watcher list.
  */
 declare class AgentTelescopeWatcher implements Watcher {
     readonly type = "agent";
+    private readonly disposers;
     register(ctx: WatcherContext): void;
+    /** Detach all channel subscriptions and release the diagnostics claim (e.g. on module destroy). */
+    dispose(): void;
 }
 
-/** The "Agent" overview dashboard. Panels bind to the `agent.*` data providers. */
-declare function agentDashboard(): DashboardSpec;
+/**
+ * The "Agent" overview dashboard. Panels bind to the `agent.*` data providers.
+ *
+ * `threadHref`/`runHref` are URL templates for deep-linking a `{threadId}`/`{runId}` cell out to
+ * the host's own thread/run viewer (e.g. the standalone `@dudousxd/nestjs-agent-dashboard` SPA),
+ * mirroring `durableTelescopeExtension`'s `runHref` option. Every table whose rows carry a
+ * `threadId`/`runId` gets a `Column.link` for it (via {@link col}); omit an option to leave that
+ * column plain text.
+ */
+declare function agentDashboard(opts?: {
+    threadHref?: string;
+    runHref?: string;
+}): DashboardSpec;
 
 /** stat → total agent runs (run.finished entries). */
 declare function agentRunsProvider(): DataProvider;
 /** stat → total tokens across all finished runs. */
 declare function agentTokensProvider(): DataProvider;
-/** table → recent tool calls. */
+/**
+ * table → recent tool calls, from Telescope's own ephemeral event storage.
+ *
+ * @deprecated Superseded in the shipped dashboard by `agentRecentToolCallsTableProvider`
+ * (`agent.tools.recent`, in `agent-governance-providers.ts`), which reads the durable,
+ * restart-surviving `AGENT_GOVERNANCE_QUERIES.recentToolCalls` read-model. That durable route is
+ * never behind this ephemeral one: `agent-loop.ts` always awaits `store.recordToolCall` /
+ * `store.updateToolCall` (the durable write) BEFORE calling `publishAgentToolCall` (the event this
+ * provider reads), so a row is durably queryable strictly before the ephemeral entry exists. The
+ * durable route also captures the `pending_approval` state this ephemeral channel never emits at
+ * all (no `publishAgentToolCall` call sits between `recordToolCall(status: 'pending_approval')`
+ * and the eventual terminal transition) — so there's no in-flight state left for this table to
+ * uniquely show. Kept exported (not removed — that would be a breaking export change) for hosts
+ * that use `agentTelescopeExtension()` without wiring `AGENT_GOVERNANCE_QUERIES`, or that compose
+ * a custom extension from these lower-level provider functions directly.
+ */
 declare function agentToolsProvider(): DataProvider;
 /** breakdown → tool-call status distribution. */
 declare function agentToolStatusProvider(): DataProvider;
@@ -58,6 +108,14 @@ interface ActorSpendTableRow {
     totalTokens: number;
     costUsd: number;
 }
+/** One row of the top-threads-by-cost table. */
+interface ThreadSpendTableRow {
+    title: string;
+    actorRef: string;
+    requests: number;
+    totalTokens: number;
+    costUsd: number;
+}
 /** One point of the timeseries trend (Telescope core: `{ label } & Record<string, number>`). */
 interface UsageTrendTableRow {
     label: string;
@@ -81,10 +139,84 @@ declare function toModelSpendSegments(rows: ModelSpendRow[]): BreakdownSegment[]
 declare function toModelSpendRows(rows: ModelSpendRow[]): ModelSpendTableRow[];
 /** Spend-by-actor as table rows. */
 declare function toActorSpendRows(rows: ActorSpendRow[]): ActorSpendTableRow[];
+/** Top-threads-by-cost as table rows. */
+declare function toThreadSpendRows(rows: ThreadSpendRow[]): ThreadSpendTableRow[];
 /** Spend-by-actor as breakdown segments (actors with zero cost are dropped). */
 declare function toActorSpendSegments(rows: ActorSpendRow[]): BreakdownSegment[];
 /** Daily usage trend as timeseries rows keyed by `label` (the day). */
 declare function toUsageTrendRows(points: UsageTrendPoint[]): UsageTrendTableRow[];
+/** Run/failure/retry rollup as table rows — `RunAgentBreakdownRow` is already table-shaped. */
+declare function toRunAgentTableRows(rows: RunAgentBreakdownRow[]): Array<{
+    agentName: string;
+    runs: number;
+    failed: number;
+    retries: number;
+}>;
+/** Failed-run counts by error code as breakdown segments. */
+declare function toRunErrorSegments(rows: RunErrorBreakdownRow[]): BreakdownSegment[];
+/** One point of the run/failure trend (Telescope core: `{ label } & Record<string, number>`). */
+interface RunTrendTableRow {
+    label: string;
+    runs: number;
+    failed: number;
+}
+/** Daily run/failure trend as timeseries rows keyed by `label` (the day). */
+declare function toRunTrendRows(points: RunTrendPoint[]): RunTrendTableRow[];
+/**
+ * Cap a run's error message to {@link ERROR_MESSAGE_CAP} characters before it leaves the provider.
+ * `DataProvider.resolve` output bypasses Telescope core's `redact()` pipeline — that only runs on
+ * entries a `Watcher` records via `ctx.record`, not on values a provider computes and returns
+ * directly to a panel — so an unbounded stack trace or secret-laden failure message would ride
+ * straight into a table cell with no truncation/redaction safety net. This cap is a stopgap
+ * mitigation, not a substitute for the (out-of-scope this wave) telescope-core redaction hook for
+ * DataProvider output.
+ */
+declare function capErrorMessage(message: string | null): string | null;
+/** Shorten a full sha256 promptHash to a compact chip for the table column. */
+declare function shortPromptHash(promptHash: string | null): string | null;
+/** One row of the recent-runs table — every nullable field falls back to {@link NO_VALUE}. */
+interface RecentRunTableRow {
+    startedAt: string;
+    runId: string;
+    threadId: string;
+    actorRef: string;
+    agentName: string;
+    status: string;
+    durationMs: number | string;
+    retries: number;
+    errorCode: string;
+    errorMessage: string;
+    promptHash: string;
+}
+/** Recent runs as table rows: errorMessage capped, promptHash shortened to a chip. */
+declare function toRecentRunTableRows(rows: RecentRunRow[]): RecentRunTableRow[];
+/** Recent tool calls as table rows — `ToolCallActivityRow` is already table-shaped. */
+declare function toRecentToolCallRows(rows: ToolCallActivityRow[]): ToolCallActivityRow[];
+/** Recent threads as table rows — `ThreadActivityRow` is already table-shaped. */
+declare function toRecentThreadTableRows(rows: ThreadActivityRow[]): ThreadActivityRow[];
+/** One row of the pending-approvals inbox table, `input` stringified for display. */
+interface PendingApprovalTableRow {
+    toolCallId: string;
+    toolName: string;
+    threadId: string;
+    threadTitle: string;
+    actorRef: string;
+    agentName: string;
+    requestedAt: string;
+}
+/** Pending-approvals rows as table rows (drops the raw `input` — not renderable in a table cell). */
+declare function toPendingApprovalTableRows(rows: PendingApprovalRow[]): PendingApprovalTableRow[];
+/** One row of the per-tool stats table, `p95ExecutionMs` falling back to {@link NO_VALUE}. */
+interface ToolStatTableRow {
+    toolName: string;
+    toolType: string;
+    calls: number;
+    failed: number;
+    rejected: number;
+    p95ExecutionMs: number | string;
+}
+/** Per-tool call/failure/rejection/latency rollup as table rows. */
+declare function toToolStatTableRows(rows: ToolStatRow[]): ToolStatTableRow[];
 /** stat → authoritative total spend (USD) over the range. */
 declare function agentSpendTotalProvider(): DataProvider;
 /** stat → authoritative total tokens (input + output) over the range. */
@@ -99,5 +231,53 @@ declare function agentUsageTrendProvider(): DataProvider;
 declare function agentActorSpendTableProvider(): DataProvider;
 /** breakdown → spend share per actor. */
 declare function agentSpendByActorProvider(): DataProvider;
+/** table → top threads by cost (title, actor, requests, tokens, cost). */
+declare function agentTopThreadsTableProvider(): DataProvider;
+/** stat → total runs over the range. */
+declare function agentRunsTotalProvider(): DataProvider;
+/** stat → completed/total success rate over the range. */
+declare function agentRunsSuccessRateProvider(): DataProvider;
+/** stat → failed run count over the range. */
+declare function agentRunsFailedProvider(): DataProvider;
+/** stat → total llm-step retries across the range's runs. */
+declare function agentRunsRetriesProvider(): DataProvider;
+/**
+ * stat → run duration percentile, selected by `query.metric` (`'p95'` for p95, anything else —
+ * including omitted — for p50), mirroring `durable.duration`'s stat shortcut. NOT a
+ * `distribution` panel: `RunMetrics` exposes only the two percentiles (no raw per-run samples to
+ * bucket into a histogram), so a distribution here would render as a permanently-empty box. A
+ * `null` percentile (no settled runs in range) resolves to 0.
+ */
+declare function agentRunsDurationProvider(): DataProvider;
+/** table → run/failure/retry rollup per agent. */
+declare function agentRunsByAgentTableProvider(): DataProvider;
+/** breakdown → failed runs by error code. */
+declare function agentRunErrorsProvider(): DataProvider;
+/** timeseries → daily runs + failures trend. */
+declare function agentRunsTrendProvider(): DataProvider;
+/**
+ * table → most recent runs (newest first), errorMessage capped and promptHash shortened to a chip
+ * — see {@link capErrorMessage} for why the cap happens here rather than downstream.
+ */
+declare function agentRecentRunsTableProvider(): DataProvider;
+/**
+ * table → most recent tool calls (newest first), from the durable read-model. Replaces the
+ * ephemeral, watcher-fed `agent.tools` provider in `agent-data-providers.ts` for the shipped
+ * dashboard — see that file's header comment for why.
+ */
+declare function agentRecentToolCallsTableProvider(): DataProvider;
+/** table → most recently active threads, with rolled-up message/token counts. */
+declare function agentRecentThreadsTableProvider(): DataProvider;
+/**
+ * stat → count of tool calls sitting `pending_approval` across every thread. The SPI's
+ * `pendingApprovals` only returns a capped list, not a true count, so this undercounts a backlog
+ * larger than {@link PENDING_APPROVALS_COUNT_LIMIT} — a backlog that size signals a bigger
+ * operational problem than an off-by-N stat, so the approximation is an acceptable tradeoff.
+ */
+declare function agentPendingApprovalsCountProvider(): DataProvider;
+/** table → the pending-approvals inbox, oldest request first. */
+declare function agentPendingApprovalsTableProvider(): DataProvider;
+/** table → per-tool call/failure/rejection/latency rollup over the range. */
+declare function agentToolStatsTableProvider(): DataProvider;
 
-export { AgentTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentRunsProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatusProvider, agentToolsProvider, agentUsageTrendProvider, resolveRange, shiftUtcDay, toActorSpendRows, toActorSpendSegments, toModelSpendRows, toModelSpendSegments, toUsageTrendRows, totalCostUsd, totalTokens };
+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 };