@dudousxd/nestjs-agent-telescope 0.8.61 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -33,7 +33,9 @@ __export(index_exports, {
33
33
  agentRecentThreadsTableProvider: () => agentRecentThreadsTableProvider,
34
34
  agentRecentToolCallsTableProvider: () => agentRecentToolCallsTableProvider,
35
35
  agentRunErrorsProvider: () => agentRunErrorsProvider,
36
+ agentRunFailureCodesProvider: () => agentRunFailureCodesProvider,
36
37
  agentRunsByAgentTableProvider: () => agentRunsByAgentTableProvider,
38
+ agentRunsCancelledProvider: () => agentRunsCancelledProvider,
37
39
  agentRunsDurationProvider: () => agentRunsDurationProvider,
38
40
  agentRunsFailedProvider: () => agentRunsFailedProvider,
39
41
  agentRunsProvider: () => agentRunsProvider,
@@ -41,6 +43,8 @@ __export(index_exports, {
41
43
  agentRunsSuccessRateProvider: () => agentRunsSuccessRateProvider,
42
44
  agentRunsTotalProvider: () => agentRunsTotalProvider,
43
45
  agentRunsTrendProvider: () => agentRunsTrendProvider,
46
+ agentRunsTtftDistributionProvider: () => agentRunsTtftDistributionProvider,
47
+ agentRunsTtftProvider: () => agentRunsTtftProvider,
44
48
  agentSpendByActorProvider: () => agentSpendByActorProvider,
45
49
  agentSpendByModelProvider: () => agentSpendByModelProvider,
46
50
  agentSpendTotalProvider: () => agentSpendTotalProvider,
@@ -72,6 +76,7 @@ __export(index_exports, {
72
76
  toActorSpendRows: () => toActorSpendRows,
73
77
  toActorSpendSegments: () => toActorSpendSegments,
74
78
  toCollectionRows: () => toCollectionRows,
79
+ toFailureCodeSegments: () => toFailureCodeSegments,
75
80
  toLatencyDistribution: () => toLatencyDistribution,
76
81
  toModelSpendRows: () => toModelSpendRows,
77
82
  toModelSpendSegments: () => toModelSpendSegments,
@@ -90,6 +95,7 @@ __export(index_exports, {
90
95
  toStoreSegments: () => toStoreSegments,
91
96
  toThreadSpendRows: () => toThreadSpendRows,
92
97
  toToolStatTableRows: () => toToolStatTableRows,
98
+ toTtftDistribution: () => toTtftDistribution,
93
99
  toUsageTrendRows: () => toUsageTrendRows,
94
100
  totalCostUsd: () => totalCostUsd,
95
101
  totalTokens: () => totalTokens,
@@ -340,6 +346,43 @@ function agentDashboard(opts = {}) {
340
346
  },
341
347
  // Two duration stats above, not a `distribution` panel: RunMetrics carries only p50/p95
342
348
  // (no raw samples to bucket), so a histogram here would be a permanently-empty box.
349
+ {
350
+ kind: "stat",
351
+ title: "TTFT p50",
352
+ data: {
353
+ provider: "agent.runs.ttft",
354
+ query: {
355
+ metric: "p50"
356
+ }
357
+ },
358
+ format: "duration"
359
+ },
360
+ {
361
+ kind: "stat",
362
+ title: "TTFT p95",
363
+ data: {
364
+ provider: "agent.runs.ttft",
365
+ query: {
366
+ metric: "p95"
367
+ }
368
+ },
369
+ format: "duration"
370
+ },
371
+ {
372
+ // The one histogram in this section: `run.finished` diagnostics carry each run's own
373
+ // `ttftMs`, so the watcher-recorded entries DO have samples to bucket (over what
374
+ // Telescope's storage still holds, not the governance range).
375
+ kind: "distribution",
376
+ title: "Time to first token",
377
+ data: {
378
+ provider: "agent.runs.ttftDistribution"
379
+ },
380
+ markers: [
381
+ "p50",
382
+ "p95"
383
+ ],
384
+ format: "duration"
385
+ },
343
386
  {
344
387
  kind: "timeseries",
345
388
  title: "Runs & failures",
@@ -387,6 +430,30 @@ function agentDashboard(opts = {}) {
387
430
  }
388
431
  ]
389
432
  },
433
+ {
434
+ // Live, from the watcher-recorded diagnostics rather than the run rows: what failed and
435
+ // what was stopped, readable on a host that binds no governance read-model. A cancel is
436
+ // its own number — a user pressing Stop is the control working, not a failure.
437
+ title: "Run outcomes",
438
+ cols: 2,
439
+ panels: [
440
+ {
441
+ kind: "breakdown",
442
+ title: "Failures by code",
443
+ data: {
444
+ provider: "agent.runs.failureCodes"
445
+ },
446
+ style: "donut"
447
+ },
448
+ {
449
+ kind: "stat",
450
+ title: "Cancelled",
451
+ data: {
452
+ provider: "agent.runs.cancelled"
453
+ }
454
+ }
455
+ ]
456
+ },
390
457
  {
391
458
  // The paged list tables: tool calls, threads, runs — each reads the paged SPI
392
459
  // (toolCallsPage/threadsPage/runsPage via `agent.*.paged`) and opts into the renderer's
@@ -783,6 +850,82 @@ function ofEvent(entries, event) {
783
850
  return entries.filter((entry) => entry.content?.event === event);
784
851
  }
785
852
  __name(ofEvent, "ofEvent");
853
+ function firstToolCalls(entries) {
854
+ return ofEvent(entries, "tool-call").filter((entry) => entry.content?.replayed !== true);
855
+ }
856
+ __name(firstToolCalls, "firstToolCalls");
857
+ function percentileOf(samples, fraction) {
858
+ if (samples.length === 0) {
859
+ return null;
860
+ }
861
+ const sorted = [
862
+ ...samples
863
+ ].sort((a, b) => a - b);
864
+ const rank = Math.ceil(fraction * sorted.length);
865
+ return sorted[Math.min(Math.max(rank, 1), sorted.length) - 1] ?? null;
866
+ }
867
+ __name(percentileOf, "percentileOf");
868
+ var TTFT_EDGES = [
869
+ 250,
870
+ 500,
871
+ 1e3,
872
+ 2e3,
873
+ 4e3,
874
+ 8e3,
875
+ 16e3
876
+ ];
877
+ function ttftLabel(index) {
878
+ const upper = TTFT_EDGES[index];
879
+ if (upper === void 0) {
880
+ return `\u2265${TTFT_EDGES[TTFT_EDGES.length - 1] ?? 0}ms`;
881
+ }
882
+ return `${index === 0 ? 0 : TTFT_EDGES[index - 1] ?? 0}\u2013${upper}ms`;
883
+ }
884
+ __name(ttftLabel, "ttftLabel");
885
+ function toTtftDistribution(entries) {
886
+ const samples = [];
887
+ const counts = new Array(TTFT_EDGES.length + 1).fill(0);
888
+ for (const entry of ofEvent(entries, "run.finished")) {
889
+ const ttftMs = entry.content?.ttftMs;
890
+ if (typeof ttftMs !== "number" || entry.content?.parentRunId !== void 0) {
891
+ continue;
892
+ }
893
+ samples.push(ttftMs);
894
+ const found = TTFT_EDGES.findIndex((edge) => ttftMs < edge);
895
+ const index = found === -1 ? TTFT_EDGES.length : found;
896
+ counts[index] = (counts[index] ?? 0) + 1;
897
+ }
898
+ const buckets = counts.map((count, index) => ({
899
+ label: ttftLabel(index),
900
+ count
901
+ }));
902
+ const p50 = percentileOf(samples, 0.5);
903
+ const p95 = percentileOf(samples, 0.95);
904
+ return {
905
+ buckets,
906
+ ...p50 !== null ? {
907
+ p50
908
+ } : {},
909
+ ...p95 !== null ? {
910
+ p95
911
+ } : {}
912
+ };
913
+ }
914
+ __name(toTtftDistribution, "toTtftDistribution");
915
+ function toFailureCodeSegments(entries) {
916
+ const counts = /* @__PURE__ */ new Map();
917
+ for (const entry of ofEvent(entries, "run.failed")) {
918
+ const code = entry.content?.code ?? "unknown";
919
+ counts.set(code, (counts.get(code) ?? 0) + 1);
920
+ }
921
+ return [
922
+ ...counts.entries()
923
+ ].map(([label, value]) => ({
924
+ label,
925
+ value
926
+ })).sort((a, b) => b.value - a.value);
927
+ }
928
+ __name(toFailureCodeSegments, "toFailureCodeSegments");
786
929
  function agentRunsProvider() {
787
930
  return {
788
931
  name: "agent.runs",
@@ -812,7 +955,7 @@ function agentToolsProvider() {
812
955
  return {
813
956
  name: "agent.tools",
814
957
  async resolve(_query, ctx) {
815
- const calls = ofEvent(await fetchEntries(ctx), "tool-call").slice(-50).reverse().map((entry) => ({
958
+ const calls = firstToolCalls(await fetchEntries(ctx)).slice(-50).reverse().map((entry) => ({
816
959
  toolName: entry.content?.toolName ?? "",
817
960
  toolType: entry.content?.toolType ?? "",
818
961
  status: entry.content?.status ?? "",
@@ -829,7 +972,7 @@ function agentToolStatusProvider() {
829
972
  return {
830
973
  name: "agent.toolStatus",
831
974
  async resolve(_query, ctx) {
832
- const calls = ofEvent(await fetchEntries(ctx), "tool-call");
975
+ const calls = firstToolCalls(await fetchEntries(ctx));
833
976
  const counts = /* @__PURE__ */ new Map();
834
977
  for (const call of calls) {
835
978
  const status = call.content?.status ?? "unknown";
@@ -847,6 +990,37 @@ function agentToolStatusProvider() {
847
990
  };
848
991
  }
849
992
  __name(agentToolStatusProvider, "agentToolStatusProvider");
993
+ function agentRunsTtftDistributionProvider() {
994
+ return {
995
+ name: "agent.runs.ttftDistribution",
996
+ async resolve(_query, ctx) {
997
+ return toTtftDistribution(await fetchEntries(ctx));
998
+ }
999
+ };
1000
+ }
1001
+ __name(agentRunsTtftDistributionProvider, "agentRunsTtftDistributionProvider");
1002
+ function agentRunFailureCodesProvider() {
1003
+ return {
1004
+ name: "agent.runs.failureCodes",
1005
+ async resolve(_query, ctx) {
1006
+ return {
1007
+ segments: toFailureCodeSegments(await fetchEntries(ctx))
1008
+ };
1009
+ }
1010
+ };
1011
+ }
1012
+ __name(agentRunFailureCodesProvider, "agentRunFailureCodesProvider");
1013
+ function agentRunsCancelledProvider() {
1014
+ return {
1015
+ name: "agent.runs.cancelled",
1016
+ async resolve(_query, ctx) {
1017
+ return {
1018
+ value: ofEvent(await fetchEntries(ctx), "run.cancelled").length
1019
+ };
1020
+ }
1021
+ };
1022
+ }
1023
+ __name(agentRunsCancelledProvider, "agentRunsCancelledProvider");
850
1024
 
851
1025
  // src/agent-governance-providers.ts
852
1026
  var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
@@ -1004,6 +1178,9 @@ function toRecentRunTableRows(rows) {
1004
1178
  agentName: row.agentName ?? NO_VALUE,
1005
1179
  status: row.status,
1006
1180
  durationMs: row.durationMs ?? NO_VALUE,
1181
+ ttftMs: row.ttftMs ?? NO_VALUE,
1182
+ costUsd: row.costUsd ?? NO_VALUE,
1183
+ modelId: row.modelId ?? NO_VALUE,
1007
1184
  retries: row.retries,
1008
1185
  errorCode: row.errorCode ?? NO_VALUE,
1009
1186
  errorMessage: capErrorMessage(row.errorMessage) ?? NO_VALUE,
@@ -1051,8 +1228,47 @@ var EMPTY_RUN_METRICS = {
1051
1228
  successRate: 0,
1052
1229
  retries: 0,
1053
1230
  durationP50Ms: null,
1054
- durationP95Ms: null
1231
+ durationP95Ms: null,
1232
+ ttftP50Ms: null,
1233
+ ttftP95Ms: null
1055
1234
  };
1235
+ var SHARED_READ_MS = 1e3;
1236
+ var sharedReads = /* @__PURE__ */ new WeakMap();
1237
+ function sharedRead(queries, key, read) {
1238
+ let reads = sharedReads.get(queries);
1239
+ if (reads === void 0) {
1240
+ reads = /* @__PURE__ */ new Map();
1241
+ sharedReads.set(queries, reads);
1242
+ }
1243
+ const pending = reads.get(key);
1244
+ if (pending !== void 0) {
1245
+ return pending;
1246
+ }
1247
+ const started = read();
1248
+ reads.set(key, started);
1249
+ const forget = /* @__PURE__ */ __name(() => {
1250
+ if (reads.get(key) === started) reads.delete(key);
1251
+ }, "forget");
1252
+ started.then(() => setTimeout(forget, SHARED_READ_MS).unref(), forget);
1253
+ return started;
1254
+ }
1255
+ __name(sharedRead, "sharedRead");
1256
+ function rangeKey(method, range) {
1257
+ return `${method}|${range.fromDay}|${range.toDay}`;
1258
+ }
1259
+ __name(rangeKey, "rangeKey");
1260
+ function spendByModel(queries, range) {
1261
+ return sharedRead(queries, rangeKey("spendByModel", range), () => queries.spendByModel(range));
1262
+ }
1263
+ __name(spendByModel, "spendByModel");
1264
+ function spendByActor(queries, range) {
1265
+ return sharedRead(queries, rangeKey("spendByActor", range), () => queries.spendByActor(range));
1266
+ }
1267
+ __name(spendByActor, "spendByActor");
1268
+ function runMetrics(queries, range) {
1269
+ return sharedRead(queries, rangeKey("runMetrics", range), () => queries.runMetrics(range));
1270
+ }
1271
+ __name(runMetrics, "runMetrics");
1056
1272
  function governanceStatProvider(name, fetch, format) {
1057
1273
  return {
1058
1274
  name,
@@ -1065,25 +1281,25 @@ function governanceStatProvider(name, fetch, format) {
1065
1281
  }
1066
1282
  __name(governanceStatProvider, "governanceStatProvider");
1067
1283
  function agentSpendTotalProvider() {
1068
- return governanceStatProvider("agent.spend.totalCost", (queries, range) => queries.spendByModel(range), (rows) => ({
1284
+ return governanceStatProvider("agent.spend.totalCost", (queries, range) => spendByModel(queries, range), (rows) => ({
1069
1285
  value: totalCostUsd(rows)
1070
1286
  }));
1071
1287
  }
1072
1288
  __name(agentSpendTotalProvider, "agentSpendTotalProvider");
1073
1289
  function agentTokensTotalProvider() {
1074
- return governanceStatProvider("agent.spend.totalTokens", (queries, range) => queries.spendByModel(range), (rows) => ({
1290
+ return governanceStatProvider("agent.spend.totalTokens", (queries, range) => spendByModel(queries, range), (rows) => ({
1075
1291
  value: totalTokens(rows)
1076
1292
  }));
1077
1293
  }
1078
1294
  __name(agentTokensTotalProvider, "agentTokensTotalProvider");
1079
1295
  function agentSpendByModelProvider() {
1080
- return governanceStatProvider("agent.spend.byModel", (queries, range) => queries.spendByModel(range), (rows) => ({
1296
+ return governanceStatProvider("agent.spend.byModel", (queries, range) => spendByModel(queries, range), (rows) => ({
1081
1297
  segments: toModelSpendSegments(rows)
1082
1298
  }));
1083
1299
  }
1084
1300
  __name(agentSpendByModelProvider, "agentSpendByModelProvider");
1085
1301
  function agentModelSpendTableProvider() {
1086
- return governanceStatProvider("agent.spend.byModelTable", (queries, range) => queries.spendByModel(range), (rows) => ({
1302
+ return governanceStatProvider("agent.spend.byModelTable", (queries, range) => spendByModel(queries, range), (rows) => ({
1087
1303
  rows: toModelSpendRows(rows)
1088
1304
  }));
1089
1305
  }
@@ -1095,13 +1311,13 @@ function agentUsageTrendProvider() {
1095
1311
  }
1096
1312
  __name(agentUsageTrendProvider, "agentUsageTrendProvider");
1097
1313
  function agentActorSpendTableProvider() {
1098
- return governanceStatProvider("agent.spend.byActor", (queries, range) => queries.spendByActor(range), (rows) => ({
1314
+ return governanceStatProvider("agent.spend.byActor", (queries, range) => spendByActor(queries, range), (rows) => ({
1099
1315
  rows: toActorSpendRows(rows)
1100
1316
  }));
1101
1317
  }
1102
1318
  __name(agentActorSpendTableProvider, "agentActorSpendTableProvider");
1103
1319
  function agentSpendByActorProvider() {
1104
- return governanceStatProvider("agent.spend.byActorShare", (queries, range) => queries.spendByActor(range), (rows) => ({
1320
+ return governanceStatProvider("agent.spend.byActorShare", (queries, range) => spendByActor(queries, range), (rows) => ({
1105
1321
  segments: toActorSpendSegments(rows)
1106
1322
  }));
1107
1323
  }
@@ -1117,7 +1333,7 @@ function governanceRunMetricsProvider(name, format) {
1117
1333
  name,
1118
1334
  async resolve(query, ctx) {
1119
1335
  const queries = resolveGovernanceQueries(ctx);
1120
- const metrics = queries ? await queries.runMetrics(resolveRange(query)) : EMPTY_RUN_METRICS;
1336
+ const metrics = queries ? await runMetrics(queries, resolveRange(query)) : EMPTY_RUN_METRICS;
1121
1337
  return format(metrics);
1122
1338
  }
1123
1339
  };
@@ -1152,7 +1368,7 @@ function agentRunsDurationProvider() {
1152
1368
  name: "agent.runs.duration",
1153
1369
  async resolve(query, ctx) {
1154
1370
  const queries = resolveGovernanceQueries(ctx);
1155
- const metrics = queries ? await queries.runMetrics(resolveRange(query)) : EMPTY_RUN_METRICS;
1371
+ const metrics = queries ? await runMetrics(queries, resolveRange(query)) : EMPTY_RUN_METRICS;
1156
1372
  const value = query?.metric === "p95" ? metrics.durationP95Ms : metrics.durationP50Ms;
1157
1373
  return {
1158
1374
  value: value ?? 0
@@ -1161,6 +1377,20 @@ function agentRunsDurationProvider() {
1161
1377
  };
1162
1378
  }
1163
1379
  __name(agentRunsDurationProvider, "agentRunsDurationProvider");
1380
+ function agentRunsTtftProvider() {
1381
+ return {
1382
+ name: "agent.runs.ttft",
1383
+ async resolve(query, ctx) {
1384
+ const queries = resolveGovernanceQueries(ctx);
1385
+ const metrics = queries ? await runMetrics(queries, resolveRange(query)) : EMPTY_RUN_METRICS;
1386
+ const value = query?.metric === "p95" ? metrics.ttftP95Ms : metrics.ttftP50Ms;
1387
+ return {
1388
+ value: value ?? 0
1389
+ };
1390
+ }
1391
+ };
1392
+ }
1393
+ __name(agentRunsTtftProvider, "agentRunsTtftProvider");
1164
1394
  function agentRunsByAgentTableProvider() {
1165
1395
  return governanceStatProvider("agent.runs.byAgent", (queries, range) => queries.runsByAgent(range), (rows) => ({
1166
1396
  rows: toRunAgentTableRows(rows)
@@ -1829,6 +2059,10 @@ function agentTelescopeExtension(opts = {}) {
1829
2059
  agentRunsFailedProvider(),
1830
2060
  agentRunsRetriesProvider(),
1831
2061
  agentRunsDurationProvider(),
2062
+ agentRunsTtftProvider(),
2063
+ agentRunsTtftDistributionProvider(),
2064
+ agentRunFailureCodesProvider(),
2065
+ agentRunsCancelledProvider(),
1832
2066
  agentRunsByAgentTableProvider(),
1833
2067
  agentRunErrorsProvider(),
1834
2068
  agentRunsTrendProvider(),
@@ -1870,7 +2104,9 @@ __name(agentTelescopeExtension, "agentTelescopeExtension");
1870
2104
  agentRecentThreadsTableProvider,
1871
2105
  agentRecentToolCallsTableProvider,
1872
2106
  agentRunErrorsProvider,
2107
+ agentRunFailureCodesProvider,
1873
2108
  agentRunsByAgentTableProvider,
2109
+ agentRunsCancelledProvider,
1874
2110
  agentRunsDurationProvider,
1875
2111
  agentRunsFailedProvider,
1876
2112
  agentRunsProvider,
@@ -1878,6 +2114,8 @@ __name(agentTelescopeExtension, "agentTelescopeExtension");
1878
2114
  agentRunsSuccessRateProvider,
1879
2115
  agentRunsTotalProvider,
1880
2116
  agentRunsTrendProvider,
2117
+ agentRunsTtftDistributionProvider,
2118
+ agentRunsTtftProvider,
1881
2119
  agentSpendByActorProvider,
1882
2120
  agentSpendByModelProvider,
1883
2121
  agentSpendTotalProvider,
@@ -1909,6 +2147,7 @@ __name(agentTelescopeExtension, "agentTelescopeExtension");
1909
2147
  toActorSpendRows,
1910
2148
  toActorSpendSegments,
1911
2149
  toCollectionRows,
2150
+ toFailureCodeSegments,
1912
2151
  toLatencyDistribution,
1913
2152
  toModelSpendRows,
1914
2153
  toModelSpendSegments,
@@ -1927,6 +2166,7 @@ __name(agentTelescopeExtension, "agentTelescopeExtension");
1927
2166
  toStoreSegments,
1928
2167
  toThreadSpendRows,
1929
2168
  toToolStatTableRows,
2169
+ toTtftDistribution,
1930
2170
  toUsageTrendRows,
1931
2171
  totalCostUsd,
1932
2172
  totalTokens,