@dudousxd/nestjs-agent-telescope 0.3.5 → 0.5.0

package/dist/index.js

@@ -4,8 +4,21 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 // src/agent-telescope.extension.ts
 import { defineTelescopeExtension } from "@dudousxd/nestjs-telescope";
 
-// src/agent-dashboard.ts
-function agentDashboard() {
+// src/agent-dashboard.spec-data.ts
+function col(key, label, href) {
+  return href !== void 0 ? {
+    key,
+    label,
+    link: {
+      href
+    }
+  } : {
+    key,
+    label
+  };
+}
+__name(col, "col");
+function agentDashboard(opts = {}) {
   return {
     id: "agent.overview",
     label: "Agent",
@@ -31,6 +44,158 @@ function agentDashboard() {
           }
         ]
       },
+      {
+        title: "Reliability",
+        cols: 4,
+        panels: [
+          {
+            kind: "stat",
+            title: "Runs",
+            data: {
+              provider: "agent.runs.total"
+            }
+          },
+          {
+            kind: "stat",
+            title: "Success rate",
+            data: {
+              provider: "agent.runs.successRate"
+            },
+            format: "percent"
+          },
+          {
+            kind: "stat",
+            title: "Failed",
+            data: {
+              provider: "agent.runs.failed"
+            }
+          },
+          {
+            kind: "stat",
+            title: "Retries",
+            data: {
+              provider: "agent.runs.retries"
+            }
+          }
+        ]
+      },
+      {
+        title: "Run trends",
+        cols: 4,
+        panels: [
+          {
+            kind: "timeseries",
+            title: "Runs & failures",
+            data: {
+              provider: "agent.runs.trend"
+            },
+            series: [
+              "runs",
+              "failed"
+            ],
+            style: "stacked"
+          },
+          // Two duration stats, not a `distribution` panel: RunMetrics carries only p50/p95 (no
+          // raw samples to bucket), so a histogram here would be a permanently-empty box.
+          {
+            kind: "stat",
+            title: "Duration p50",
+            data: {
+              provider: "agent.runs.duration",
+              query: {
+                metric: "p50"
+              }
+            },
+            format: "duration"
+          },
+          {
+            kind: "stat",
+            title: "Duration p95",
+            data: {
+              provider: "agent.runs.duration",
+              query: {
+                metric: "p95"
+              }
+            },
+            format: "duration"
+          },
+          {
+            kind: "breakdown",
+            title: "Run errors",
+            data: {
+              provider: "agent.runs.errors"
+            },
+            style: "donut"
+          }
+        ]
+      },
+      {
+        title: "Runs",
+        panels: [
+          {
+            kind: "table",
+            title: "Runs by agent",
+            data: {
+              provider: "agent.runs.byAgent"
+            },
+            columns: [
+              {
+                key: "agentName",
+                label: "Agent"
+              },
+              {
+                key: "runs",
+                label: "Runs"
+              },
+              {
+                key: "failed",
+                label: "Failed"
+              },
+              {
+                key: "retries",
+                label: "Retries"
+              }
+            ]
+          },
+          {
+            kind: "table",
+            title: "Recent runs",
+            data: {
+              provider: "agent.runs.recent"
+            },
+            // A deliberate SUBSET of the provider's row shape: the full 11-field row overflows the
+            // card horizontally. Thread/actor/retries/errorCode detail lives in the standalone
+            // agent dashboard; the provider keeps returning the full row for other consumers.
+            columns: [
+              {
+                key: "startedAt",
+                label: "Started"
+              },
+              col("runId", "Run", opts.runHref),
+              {
+                key: "agentName",
+                label: "Agent"
+              },
+              {
+                key: "status",
+                label: "Status"
+              },
+              {
+                key: "durationMs",
+                label: "Duration (ms)"
+              },
+              {
+                key: "errorMessage",
+                label: "Error"
+              },
+              {
+                key: "promptHash",
+                label: "Prompt"
+              }
+            ]
+          }
+        ]
+      },
       {
         title: "Spend",
         cols: 2,
@@ -148,6 +313,7 @@ function agentDashboard() {
       },
       {
         title: "Threads",
+        cols: 2,
         panels: [
           {
             kind: "table",
@@ -177,6 +343,79 @@ function agentDashboard() {
                 label: "Cost (USD)"
               }
             ]
+          },
+          {
+            kind: "table",
+            title: "Recently active threads",
+            data: {
+              provider: "agent.threads.recent"
+            },
+            columns: [
+              col("threadId", "Thread", opts.threadHref),
+              {
+                key: "title",
+                label: "Title"
+              },
+              {
+                key: "actorRef",
+                label: "Actor"
+              },
+              {
+                key: "messageCount",
+                label: "Messages"
+              },
+              {
+                key: "totalTokens",
+                label: "Tokens"
+              },
+              {
+                key: "lastActivityAt",
+                label: "Last activity"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        title: "Approvals",
+        cols: 3,
+        panels: [
+          {
+            kind: "stat",
+            title: "Pending approvals",
+            data: {
+              provider: "agent.approvals.pending"
+            }
+          },
+          {
+            kind: "table",
+            title: "Approvals inbox",
+            data: {
+              provider: "agent.approvals.recent"
+            },
+            columns: [
+              {
+                key: "requestedAt",
+                label: "Requested"
+              },
+              {
+                key: "toolName",
+                label: "Tool"
+              },
+              {
+                key: "threadTitle",
+                label: "Thread"
+              },
+              col("threadId", "Thread id", opts.threadHref),
+              {
+                key: "actorRef",
+                label: "Actor"
+              },
+              {
+                key: "agentName",
+                label: "Agent"
+              }
+            ]
           }
         ]
       },
@@ -192,13 +431,50 @@ function agentDashboard() {
             },
             style: "donut"
           },
+          {
+            kind: "table",
+            title: "Tool stats",
+            data: {
+              provider: "agent.tools.stats"
+            },
+            columns: [
+              {
+                key: "toolName",
+                label: "Tool"
+              },
+              {
+                key: "toolType",
+                label: "Type"
+              },
+              {
+                key: "calls",
+                label: "Calls"
+              },
+              {
+                key: "failed",
+                label: "Failed"
+              },
+              {
+                key: "rejected",
+                label: "Rejected"
+              },
+              {
+                key: "p95ExecutionMs",
+                label: "p95 (ms)"
+              }
+            ]
+          },
           {
             kind: "table",
             title: "Recent tool calls",
             data: {
-              provider: "agent.tools"
+              provider: "agent.tools.recent"
             },
             columns: [
+              {
+                key: "createdAt",
+                label: "When"
+              },
               {
                 key: "toolName",
                 label: "Tool"
@@ -211,10 +487,7 @@ function agentDashboard() {
                 key: "status",
                 label: "Status"
               },
-              {
-                key: "runId",
-                label: "Run"
-              }
+              col("threadId", "Thread", opts.threadHref)
             ]
           }
         ]
@@ -316,7 +589,7 @@ function isRecord(value) {
 }
 __name(isRecord, "isRecord");
 function isGovernanceQueries(value) {
-  return isRecord(value) && typeof value.spendByModel === "function" && typeof value.spendByActor === "function" && typeof value.spendByThread === "function" && typeof value.usageTrend === "function" && typeof value.recentToolCalls === "function" && typeof value.recentThreads === "function";
+  return isRecord(value) && typeof value.spendByModel === "function" && typeof value.spendByActor === "function" && typeof value.spendByThread === "function" && typeof value.usageTrend === "function" && typeof value.recentToolCalls === "function" && typeof value.recentThreads === "function" && typeof value.runMetrics === "function" && typeof value.runsByAgent === "function" && typeof value.runErrors === "function" && typeof value.runTrend === "function" && typeof value.recentRuns === "function" && typeof value.pendingApprovals === "function" && typeof value.toolStats === "function";
 }
 __name(isGovernanceQueries, "isGovernanceQueries");
 function resolveGovernanceQueries(ctx) {
@@ -417,6 +690,98 @@ function toUsageTrendRows(points) {
   }));
 }
 __name(toUsageTrendRows, "toUsageTrendRows");
+var NO_VALUE = "\u2014";
+function toRunAgentTableRows(rows) {
+  return rows.map((row) => ({
+    agentName: row.agentName,
+    runs: row.runs,
+    failed: row.failed,
+    retries: row.retries
+  }));
+}
+__name(toRunAgentTableRows, "toRunAgentTableRows");
+function toRunErrorSegments(rows) {
+  return rows.map((row) => ({
+    label: row.errorCode,
+    value: row.count
+  }));
+}
+__name(toRunErrorSegments, "toRunErrorSegments");
+function toRunTrendRows(points) {
+  return points.map((point) => ({
+    label: point.day,
+    runs: point.runs,
+    failed: point.failed
+  }));
+}
+__name(toRunTrendRows, "toRunTrendRows");
+var ERROR_MESSAGE_CAP = 500;
+function capErrorMessage(message) {
+  if (message === null) return null;
+  return message.length > ERROR_MESSAGE_CAP ? `${message.slice(0, ERROR_MESSAGE_CAP)}\u2026` : message;
+}
+__name(capErrorMessage, "capErrorMessage");
+var PROMPT_HASH_CHIP_LENGTH = 10;
+function shortPromptHash(promptHash) {
+  return promptHash === null ? null : promptHash.slice(0, PROMPT_HASH_CHIP_LENGTH);
+}
+__name(shortPromptHash, "shortPromptHash");
+function toRecentRunTableRows(rows) {
+  return rows.map((row) => ({
+    startedAt: row.startedAt,
+    runId: row.runId,
+    threadId: row.threadId,
+    actorRef: row.actorRef,
+    agentName: row.agentName ?? NO_VALUE,
+    status: row.status,
+    durationMs: row.durationMs ?? NO_VALUE,
+    retries: row.retries,
+    errorCode: row.errorCode ?? NO_VALUE,
+    errorMessage: capErrorMessage(row.errorMessage) ?? NO_VALUE,
+    promptHash: shortPromptHash(row.promptHash) ?? NO_VALUE
+  }));
+}
+__name(toRecentRunTableRows, "toRecentRunTableRows");
+function toRecentToolCallRows(rows) {
+  return rows;
+}
+__name(toRecentToolCallRows, "toRecentToolCallRows");
+function toRecentThreadTableRows(rows) {
+  return rows;
+}
+__name(toRecentThreadTableRows, "toRecentThreadTableRows");
+function toPendingApprovalTableRows(rows) {
+  return rows.map((row) => ({
+    toolCallId: row.toolCallId,
+    toolName: row.toolName,
+    threadId: row.threadId,
+    threadTitle: row.threadTitle,
+    actorRef: row.actorRef,
+    agentName: row.agentName ?? NO_VALUE,
+    requestedAt: row.requestedAt
+  }));
+}
+__name(toPendingApprovalTableRows, "toPendingApprovalTableRows");
+function toToolStatTableRows(rows) {
+  return rows.map((row) => ({
+    toolName: row.toolName,
+    toolType: row.toolType,
+    calls: row.calls,
+    failed: row.failed,
+    rejected: row.rejected,
+    p95ExecutionMs: row.p95ExecutionMs ?? NO_VALUE
+  }));
+}
+__name(toToolStatTableRows, "toToolStatTableRows");
+var EMPTY_RUN_METRICS = {
+  runs: 0,
+  completed: 0,
+  failed: 0,
+  successRate: 0,
+  retries: 0,
+  durationP50Ms: null,
+  durationP95Ms: null
+};
 function governanceStatProvider(name, fetch, format) {
   return {
     name,
@@ -476,25 +841,152 @@ function agentTopThreadsTableProvider() {
   }));
 }
 __name(agentTopThreadsTableProvider, "agentTopThreadsTableProvider");
+function governanceRunMetricsProvider(name, format) {
+  return {
+    name,
+    async resolve(query, ctx) {
+      const queries = resolveGovernanceQueries(ctx);
+      const metrics = queries ? await queries.runMetrics(resolveRange(query)) : EMPTY_RUN_METRICS;
+      return format(metrics);
+    }
+  };
+}
+__name(governanceRunMetricsProvider, "governanceRunMetricsProvider");
+function agentRunsTotalProvider() {
+  return governanceRunMetricsProvider("agent.runs.total", (metrics) => ({
+    value: metrics.runs
+  }));
+}
+__name(agentRunsTotalProvider, "agentRunsTotalProvider");
+function agentRunsSuccessRateProvider() {
+  return governanceRunMetricsProvider("agent.runs.successRate", (metrics) => ({
+    value: metrics.successRate
+  }));
+}
+__name(agentRunsSuccessRateProvider, "agentRunsSuccessRateProvider");
+function agentRunsFailedProvider() {
+  return governanceRunMetricsProvider("agent.runs.failed", (metrics) => ({
+    value: metrics.failed
+  }));
+}
+__name(agentRunsFailedProvider, "agentRunsFailedProvider");
+function agentRunsRetriesProvider() {
+  return governanceRunMetricsProvider("agent.runs.retries", (metrics) => ({
+    value: metrics.retries
+  }));
+}
+__name(agentRunsRetriesProvider, "agentRunsRetriesProvider");
+function agentRunsDurationProvider() {
+  return {
+    name: "agent.runs.duration",
+    async resolve(query, ctx) {
+      const queries = resolveGovernanceQueries(ctx);
+      const metrics = queries ? await queries.runMetrics(resolveRange(query)) : EMPTY_RUN_METRICS;
+      const value = query?.metric === "p95" ? metrics.durationP95Ms : metrics.durationP50Ms;
+      return {
+        value: value ?? 0
+      };
+    }
+  };
+}
+__name(agentRunsDurationProvider, "agentRunsDurationProvider");
+function agentRunsByAgentTableProvider() {
+  return governanceStatProvider("agent.runs.byAgent", (queries, range) => queries.runsByAgent(range), (rows) => ({
+    rows: toRunAgentTableRows(rows)
+  }));
+}
+__name(agentRunsByAgentTableProvider, "agentRunsByAgentTableProvider");
+function agentRunErrorsProvider() {
+  return governanceStatProvider("agent.runs.errors", (queries, range) => queries.runErrors(range), (rows) => ({
+    segments: toRunErrorSegments(rows)
+  }));
+}
+__name(agentRunErrorsProvider, "agentRunErrorsProvider");
+function agentRunsTrendProvider() {
+  return governanceStatProvider("agent.runs.trend", (queries, range) => queries.runTrend(range), (points) => ({
+    rows: toRunTrendRows(points)
+  }));
+}
+__name(agentRunsTrendProvider, "agentRunsTrendProvider");
+var DEFAULT_RECENT_LIMIT = 50;
+var MAX_RECENT_LIMIT = 500;
+function resolveLimit(query, fallback) {
+  const raw = query?.limit;
+  const value = typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+  return Math.min(MAX_RECENT_LIMIT, Math.max(1, Math.trunc(value)));
+}
+__name(resolveLimit, "resolveLimit");
+function governanceLimitProvider(name, defaultLimit, fetch, format) {
+  return {
+    name,
+    async resolve(query, ctx) {
+      const queries = resolveGovernanceQueries(ctx);
+      const rows = queries ? await fetch(queries, resolveLimit(query, defaultLimit)) : [];
+      return format(rows);
+    }
+  };
+}
+__name(governanceLimitProvider, "governanceLimitProvider");
+function agentRecentRunsTableProvider() {
+  return governanceLimitProvider("agent.runs.recent", DEFAULT_RECENT_LIMIT, (queries, limit) => queries.recentRuns(limit), (rows) => ({
+    rows: toRecentRunTableRows(rows)
+  }));
+}
+__name(agentRecentRunsTableProvider, "agentRecentRunsTableProvider");
+function agentRecentToolCallsTableProvider() {
+  return governanceLimitProvider("agent.tools.recent", DEFAULT_RECENT_LIMIT, (queries, limit) => queries.recentToolCalls(limit), (rows) => ({
+    rows: toRecentToolCallRows(rows)
+  }));
+}
+__name(agentRecentToolCallsTableProvider, "agentRecentToolCallsTableProvider");
+function agentRecentThreadsTableProvider() {
+  return governanceLimitProvider("agent.threads.recent", DEFAULT_RECENT_LIMIT, (queries, limit) => queries.recentThreads(limit), (rows) => ({
+    rows: toRecentThreadTableRows(rows)
+  }));
+}
+__name(agentRecentThreadsTableProvider, "agentRecentThreadsTableProvider");
+var PENDING_APPROVALS_COUNT_LIMIT = 500;
+function agentPendingApprovalsCountProvider() {
+  return {
+    name: "agent.approvals.pending",
+    async resolve(_query, ctx) {
+      const queries = resolveGovernanceQueries(ctx);
+      const rows = queries ? await queries.pendingApprovals(PENDING_APPROVALS_COUNT_LIMIT) : [];
+      return {
+        value: rows.length
+      };
+    }
+  };
+}
+__name(agentPendingApprovalsCountProvider, "agentPendingApprovalsCountProvider");
+function agentPendingApprovalsTableProvider() {
+  return governanceLimitProvider("agent.approvals.recent", DEFAULT_RECENT_LIMIT, (queries, limit) => queries.pendingApprovals(limit), (rows) => ({
+    rows: toPendingApprovalTableRows(rows)
+  }));
+}
+__name(agentPendingApprovalsTableProvider, "agentPendingApprovalsTableProvider");
+function agentToolStatsTableProvider() {
+  return governanceStatProvider("agent.tools.stats", (queries, range) => queries.toolStats(range), (rows) => ({
+    rows: toToolStatTableRows(rows)
+  }));
+}
+__name(agentToolStatsTableProvider, "agentToolStatsTableProvider");
 
 // src/agent-telescope.watcher.ts
-import { subscribe } from "node:diagnostics_channel";
-import { channelName } from "@dudousxd/nestjs-diagnostics";
-var AGENT_EVENTS = [
-  "run.started",
-  "message",
-  "tool-call",
-  "quota.exceeded",
-  "run.finished"
-];
+import { subscribe, unsubscribe } from "node:diagnostics_channel";
+import { AGENT_DIAGNOSTIC_EVENTS } from "@dudousxd/nestjs-agent-core";
+import { channelName, claimDiagnostics } from "@dudousxd/nestjs-diagnostics";
 var AgentTelescopeWatcher = class {
   static {
     __name(this, "AgentTelescopeWatcher");
   }
   type = "agent";
+  disposers = [];
   register(ctx) {
-    for (const event of AGENT_EVENTS) {
-      subscribe(channelName("agent", event), (message) => {
+    this.disposers.push(claimDiagnostics("agent", AGENT_DIAGNOSTIC_EVENTS));
+    for (const event of AGENT_DIAGNOSTIC_EVENTS) {
+      const channel = channelName("agent", event);
+      const onMessage = /* @__PURE__ */ __name((message) => {
         const envelope = message;
         ctx.record({
           type: "agent",
@@ -506,13 +998,19 @@ var AgentTelescopeWatcher = class {
             envelope.event
           ]
         });
-      });
+      }, "onMessage");
+      subscribe(channel, onMessage);
+      this.disposers.push(() => unsubscribe(channel, onMessage));
     }
   }
+  /** Detach all channel subscriptions and release the diagnostics claim (e.g. on module destroy). */
+  dispose() {
+    while (this.disposers.length) this.disposers.pop()?.();
+  }
 };
 
 // src/agent-telescope.extension.ts
-function agentTelescopeExtension() {
+function agentTelescopeExtension(opts = {}) {
   return defineTelescopeExtension({
     name: "agent",
     watchers: /* @__PURE__ */ __name(() => [
@@ -526,12 +1024,11 @@ function agentTelescopeExtension() {
       }
     ], "entryTypes"),
     dashboards: /* @__PURE__ */ __name(() => [
-      agentDashboard()
+      agentDashboard(opts)
     ], "dashboards"),
     dataProviders: /* @__PURE__ */ __name(() => [
       agentRunsProvider(),
       agentTokensProvider(),
-      agentToolsProvider(),
       agentToolStatusProvider(),
       agentSpendTotalProvider(),
       agentTokensTotalProvider(),
@@ -540,7 +1037,21 @@ function agentTelescopeExtension() {
       agentUsageTrendProvider(),
       agentActorSpendTableProvider(),
       agentSpendByActorProvider(),
-      agentTopThreadsTableProvider()
+      agentTopThreadsTableProvider(),
+      agentRunsTotalProvider(),
+      agentRunsSuccessRateProvider(),
+      agentRunsFailedProvider(),
+      agentRunsRetriesProvider(),
+      agentRunsDurationProvider(),
+      agentRunsByAgentTableProvider(),
+      agentRunErrorsProvider(),
+      agentRunsTrendProvider(),
+      agentRecentRunsTableProvider(),
+      agentRecentToolCallsTableProvider(),
+      agentRecentThreadsTableProvider(),
+      agentPendingApprovalsCountProvider(),
+      agentPendingApprovalsTableProvider(),
+      agentToolStatsTableProvider()
     ], "dataProviders")
   });
 }
@@ -550,22 +1061,48 @@ export {
   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