@dudousxd/nestjs-agent-telescope 0.1.0
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/LICENSE +21 -0
- package/README.md +61 -0
- package/dist/index.cjs +641 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +103 -0
- package/dist/index.d.ts +103 -0
- package/dist/index.js +594 -0
- package/dist/index.js.map +1 -0
- package/package.json +42 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/agent-telescope.extension.ts","../src/agent-dashboard.ts","../src/agent-data-providers.ts","../src/agent-governance-providers.ts","../src/agent-telescope.watcher.ts"],"sourcesContent":["export { agentTelescopeExtension } from './agent-telescope.extension.js';\nexport { AgentTelescopeWatcher } from './agent-telescope.watcher.js';\nexport { agentDashboard } from './agent-dashboard.js';\nexport {\n agentRunsProvider,\n agentTokensProvider,\n agentToolsProvider,\n agentToolStatusProvider,\n} from './agent-data-providers.js';\nexport {\n agentActorSpendTableProvider,\n agentModelSpendTableProvider,\n agentSpendByActorProvider,\n agentSpendByModelProvider,\n agentSpendTotalProvider,\n agentTokensTotalProvider,\n agentUsageTrendProvider,\n resolveRange,\n shiftUtcDay,\n toActorSpendRows,\n toActorSpendSegments,\n toModelSpendRows,\n toModelSpendSegments,\n totalCostUsd,\n totalTokens,\n toUsageTrendRows,\n} from './agent-governance-providers.js';\n","import { defineTelescopeExtension } from '@dudousxd/nestjs-telescope';\nimport { agentDashboard } from './agent-dashboard.js';\nimport {\n agentRunsProvider,\n agentTokensProvider,\n agentToolStatusProvider,\n agentToolsProvider,\n} from './agent-data-providers.js';\nimport {\n agentActorSpendTableProvider,\n agentModelSpendTableProvider,\n agentSpendByActorProvider,\n agentSpendByModelProvider,\n agentSpendTotalProvider,\n agentTokensTotalProvider,\n agentUsageTrendProvider,\n} from './agent-governance-providers.js';\nimport { AgentTelescopeWatcher } from './agent-telescope.watcher.js';\n\n/**\n * The first-class Telescope extension for nestjs-agent: an \"Agent\" tab fed by two sources —\n * the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, and the\n * authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage) via the governance\n * providers. The extension `name`, entry-type id, dashboard id, and every provider name share the\n * `agent` prefix so the registry's global-uniqueness namespaces never collide with sibling extensions.\n *\n * Host wiring: the governance (Spend/Models/Actors) panels resolve `AGENT_GOVERNANCE_QUERIES` from\n * the host DI container at request time (via `ctx.moduleRef`). The host must bind that token — from\n * its store adapter (e.g. `store-mikro-orm` / `store-drizzle` / `testing`) — in the same module that\n * registers `TelescopeModule.forRoot({ extensions: [agentTelescopeExtension()] })`. If the binding is\n * absent, those panels render an empty state; the live watcher-fed panels keep working regardless.\n */\nexport function agentTelescopeExtension() {\n return defineTelescopeExtension({\n name: 'agent',\n watchers: () => [new AgentTelescopeWatcher()],\n entryTypes: () => [{ id: 'agent', label: 'Agent', dot: 'bg-violet-400' }],\n dashboards: () => [agentDashboard()],\n dataProviders: () => [\n agentRunsProvider(),\n agentTokensProvider(),\n agentToolsProvider(),\n agentToolStatusProvider(),\n agentSpendTotalProvider(),\n agentTokensTotalProvider(),\n agentSpendByModelProvider(),\n agentModelSpendTableProvider(),\n agentUsageTrendProvider(),\n agentActorSpendTableProvider(),\n agentSpendByActorProvider(),\n ],\n });\n}\n","import type { DashboardSpec } from '@dudousxd/nestjs-telescope';\n\n/** The \"Agent\" overview dashboard. Panels bind to the `agent.*` data providers. */\nexport function agentDashboard(): DashboardSpec {\n return {\n id: 'agent.overview',\n label: 'Agent',\n panels: [],\n sections: [\n {\n title: 'Overview',\n cols: 2,\n panels: [\n { kind: 'stat', title: 'Runs', data: { provider: 'agent.runs' } },\n { kind: 'stat', title: 'Tokens', data: { provider: 'agent.tokens' } },\n ],\n },\n {\n title: 'Spend',\n cols: 2,\n panels: [\n {\n kind: 'stat',\n title: 'Total spend (USD)',\n data: { provider: 'agent.spend.totalCost' },\n format: 'number',\n },\n {\n kind: 'stat',\n title: 'Total tokens',\n data: { provider: 'agent.spend.totalTokens' },\n format: 'number',\n },\n {\n kind: 'breakdown',\n title: 'Spend by model',\n data: { provider: 'agent.spend.byModel' },\n style: 'donut',\n },\n {\n kind: 'timeseries',\n title: 'Daily spend & tokens',\n data: { provider: 'agent.usage.trend' },\n series: ['costUsd', 'totalTokens'],\n style: 'area',\n },\n ],\n },\n {\n title: 'Models',\n panels: [\n {\n kind: 'table',\n title: 'Usage & cost by model',\n data: { provider: 'agent.spend.byModelTable' },\n columns: [\n { key: 'modelId', label: 'Model' },\n { key: 'requests', label: 'Requests' },\n { key: 'inputTokens', label: 'Input tokens' },\n { key: 'outputTokens', label: 'Output tokens' },\n { key: 'costUsd', label: 'Cost (USD)' },\n ],\n },\n ],\n },\n {\n title: 'Actors',\n cols: 2,\n panels: [\n {\n kind: 'breakdown',\n title: 'Spend share by actor',\n data: { provider: 'agent.spend.byActorShare' },\n style: 'bar',\n },\n {\n kind: 'table',\n title: 'Spend by actor',\n data: { provider: 'agent.spend.byActor' },\n columns: [\n { key: 'actorRef', label: 'Actor' },\n { key: 'requests', label: 'Requests' },\n { key: 'totalTokens', label: 'Tokens' },\n { key: 'costUsd', label: 'Cost (USD)' },\n ],\n },\n ],\n },\n {\n title: 'Tools',\n cols: 2,\n panels: [\n {\n kind: 'breakdown',\n title: 'Tool-call status',\n data: { provider: 'agent.toolStatus' },\n style: 'donut',\n },\n {\n kind: 'table',\n title: 'Recent tool calls',\n data: { provider: 'agent.tools' },\n columns: [\n { key: 'toolName', label: 'Tool' },\n { key: 'toolType', label: 'Type' },\n { key: 'status', label: 'Status' },\n { key: 'runId', label: 'Run' },\n ],\n },\n ],\n },\n ],\n };\n}\n","import type { DataProvider, ExtensionContext } from '@dudousxd/nestjs-telescope';\nimport { TELESCOPE_STORAGE } from '@dudousxd/nestjs-telescope';\n\ninterface AgentEntryContent {\n event: string;\n runId?: string;\n threadId?: string;\n toolName?: string;\n toolType?: string;\n status?: string;\n steps?: number;\n inputTokens?: number;\n outputTokens?: number;\n}\n\ninterface StorageEntry {\n content?: AgentEntryContent;\n createdAt?: Date;\n}\n\nasync function fetchEntries(ctx: ExtensionContext): Promise<StorageEntry[]> {\n const storage = ctx.moduleRef.get(TELESCOPE_STORAGE, { strict: false }) as {\n get(query: { type?: string; limit?: number }): Promise<{ data: StorageEntry[] }>;\n };\n const page = await storage.get({ type: 'agent', limit: 5_000 });\n return page.data;\n}\n\nfunction ofEvent(entries: StorageEntry[], event: string): StorageEntry[] {\n return entries.filter((entry) => entry.content?.event === event);\n}\n\n/** stat → total agent runs (run.finished entries). */\nexport function agentRunsProvider(): DataProvider {\n return {\n name: 'agent.runs',\n async resolve(_query, ctx) {\n const finished = ofEvent(await fetchEntries(ctx), 'run.finished');\n return { value: finished.length };\n },\n };\n}\n\n/** stat → total tokens across all finished runs. */\nexport function agentTokensProvider(): DataProvider {\n return {\n name: 'agent.tokens',\n async resolve(_query, ctx) {\n const finished = ofEvent(await fetchEntries(ctx), 'run.finished');\n const value = finished.reduce(\n (sum, entry) =>\n sum + (entry.content?.inputTokens ?? 0) + (entry.content?.outputTokens ?? 0),\n 0,\n );\n return { value };\n },\n };\n}\n\n/** table → recent tool calls. */\nexport function agentToolsProvider(): DataProvider {\n return {\n name: 'agent.tools',\n async resolve(_query, ctx) {\n const calls = ofEvent(await fetchEntries(ctx), 'tool-call')\n .slice(-50)\n .reverse()\n .map((entry) => ({\n toolName: entry.content?.toolName ?? '',\n toolType: entry.content?.toolType ?? '',\n status: entry.content?.status ?? '',\n runId: entry.content?.runId ?? '',\n }));\n return { rows: calls };\n },\n };\n}\n\n/** breakdown → tool-call status distribution. */\nexport function agentToolStatusProvider(): DataProvider {\n return {\n name: 'agent.toolStatus',\n async resolve(_query, ctx) {\n const calls = ofEvent(await fetchEntries(ctx), 'tool-call');\n const counts = new Map<string, number>();\n for (const call of calls) {\n const status = call.content?.status ?? 'unknown';\n counts.set(status, (counts.get(status) ?? 0) + 1);\n }\n return { segments: [...counts.entries()].map(([label, value]) => ({ label, value })) };\n },\n };\n}\n","import type {\n ActorSpendRow,\n AgentGovernanceQueries,\n GovernanceRange,\n ModelSpendRow,\n UsageTrendPoint,\n} from '@dudousxd/nestjs-agent-core';\nimport { AGENT_GOVERNANCE_QUERIES } from '@dudousxd/nestjs-agent-core';\nimport type { DataProvider, ExtensionContext } from '@dudousxd/nestjs-telescope';\n\n/**\n * Governance data providers for the \"Agent\" Telescope tab. Unlike the live watcher-fed providers\n * in `agent-data-providers.ts` (which read the ephemeral Telescope event storage), these read the\n * authoritative, restart-surviving read-model: `AGENT_GOVERNANCE_QUERIES` (usage ⋈ pricing).\n *\n * The read-model is resolved from the host's DI container via `ctx.moduleRef` — the exact same\n * mechanism the existing providers use for `TELESCOPE_STORAGE`. The host must bind\n * `AGENT_GOVERNANCE_QUERIES` (from its store adapter) in the same module that registers Telescope;\n * when the binding is absent every provider degrades to an empty-but-valid shape rather than throwing.\n */\n\n/** Default trailing window (in days, inclusive) when a panel query omits an explicit range. */\nconst DEFAULT_TREND_WINDOW_DAYS = 30;\n\nconst ISO_DAY_PATTERN = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/** A breakdown-panel segment (Telescope core: `{ segments: Array<{ label, value, color? }> }`). */\ninterface BreakdownSegment {\n label: string;\n value: number;\n}\n\n/** One row of the per-model usage/cost table. */\ninterface ModelSpendTableRow {\n modelId: string;\n requests: number;\n inputTokens: number;\n outputTokens: number;\n costUsd: number;\n}\n\n/** One row of the per-actor spend table. */\ninterface ActorSpendTableRow {\n actorRef: string;\n requests: number;\n totalTokens: number;\n costUsd: number;\n}\n\n/** One point of the timeseries trend (Telescope core: `{ label } & Record<string, number>`). */\ninterface UsageTrendTableRow {\n label: string;\n costUsd: number;\n totalTokens: number;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n return typeof value === 'object' && value !== null;\n}\n\n/** Structural guard so the DI-resolved binding is narrowed without an `as`/`any` cast. */\nfunction isGovernanceQueries(value: unknown): value is AgentGovernanceQueries {\n return (\n isRecord(value) &&\n typeof value.spendByModel === 'function' &&\n typeof value.spendByActor === 'function' &&\n typeof value.usageTrend === 'function' &&\n typeof value.recentToolCalls === 'function' &&\n typeof value.recentThreads === 'function'\n );\n}\n\n/**\n * Resolve the governance read-model from the host container. Returns `null` when the host has not\n * bound `AGENT_GOVERNANCE_QUERIES` (missing token throws inside `moduleRef.get`) so panels can render\n * an empty state instead of erroring.\n */\nfunction resolveGovernanceQueries(ctx: ExtensionContext): AgentGovernanceQueries | null {\n let resolved: unknown;\n try {\n resolved = ctx.moduleRef.get(AGENT_GOVERNANCE_QUERIES, { strict: false });\n } catch {\n return null;\n }\n return isGovernanceQueries(resolved) ? resolved : null;\n}\n\nfunction isIsoDay(value: unknown): value is string {\n return typeof value === 'string' && ISO_DAY_PATTERN.test(value);\n}\n\nfunction todayUtcDay(): string {\n return new Date().toISOString().slice(0, 10);\n}\n\n/** Shift a `YYYY-MM-DD` UTC day by `deltaDays` (negative goes back in time). */\nexport function shiftUtcDay(day: string, deltaDays: number): string {\n const shifted = new Date(`${day}T00:00:00.000Z`);\n shifted.setUTCDate(shifted.getUTCDate() + deltaDays);\n return shifted.toISOString().slice(0, 10);\n}\n\n/**\n * Derive the query range: honour explicit `fromDay`/`toDay` (validated ISO days), otherwise default\n * to the trailing {@link DEFAULT_TREND_WINDOW_DAYS}-day window ending today (UTC).\n */\nexport function resolveRange(query: Record<string, unknown> | undefined): GovernanceRange {\n const toDay = query && isIsoDay(query.toDay) ? query.toDay : todayUtcDay();\n const fromDay =\n query && isIsoDay(query.fromDay)\n ? query.fromDay\n : shiftUtcDay(toDay, -(DEFAULT_TREND_WINDOW_DAYS - 1));\n return { fromDay, toDay };\n}\n\nfunction roundCents(value: number): number {\n return Math.round(value * 100) / 100;\n}\n\n/** Sum authoritative spend across every model row. */\nexport function totalCostUsd(rows: ModelSpendRow[]): number {\n return roundCents(rows.reduce((sum, row) => sum + row.costUsd, 0));\n}\n\n/** Sum input + output tokens across every model row. */\nexport function totalTokens(rows: ModelSpendRow[]): number {\n return rows.reduce((sum, row) => sum + row.inputTokens + row.outputTokens, 0);\n}\n\n/** Spend-by-model as breakdown segments (models with zero cost are dropped from the donut). */\nexport function toModelSpendSegments(rows: ModelSpendRow[]): BreakdownSegment[] {\n return rows\n .filter((row) => row.costUsd > 0)\n .map((row) => ({ label: row.modelId, value: roundCents(row.costUsd) }));\n}\n\n/** Spend-by-model as table rows (cost rounded to cents; usage kept exact). */\nexport function toModelSpendRows(rows: ModelSpendRow[]): ModelSpendTableRow[] {\n return rows.map((row) => ({\n modelId: row.modelId,\n requests: row.requests,\n inputTokens: row.inputTokens,\n outputTokens: row.outputTokens,\n costUsd: roundCents(row.costUsd),\n }));\n}\n\n/** Spend-by-actor as table rows. */\nexport function toActorSpendRows(rows: ActorSpendRow[]): ActorSpendTableRow[] {\n return rows.map((row) => ({\n actorRef: row.actorRef,\n requests: row.requests,\n totalTokens: row.totalTokens,\n costUsd: roundCents(row.costUsd),\n }));\n}\n\n/** Spend-by-actor as breakdown segments (actors with zero cost are dropped). */\nexport function toActorSpendSegments(rows: ActorSpendRow[]): BreakdownSegment[] {\n return rows\n .filter((row) => row.costUsd > 0)\n .map((row) => ({ label: row.actorRef, value: roundCents(row.costUsd) }));\n}\n\n/** Daily usage trend as timeseries rows keyed by `label` (the day). */\nexport function toUsageTrendRows(points: UsageTrendPoint[]): UsageTrendTableRow[] {\n return points.map((point) => ({\n label: point.day,\n costUsd: roundCents(point.costUsd),\n totalTokens: point.totalTokens,\n }));\n}\n\n/** stat → authoritative total spend (USD) over the range. */\nexport function agentSpendTotalProvider(): DataProvider {\n return {\n name: 'agent.spend.totalCost',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { value: 0 };\n }\n const byModel = await queries.spendByModel(resolveRange(query));\n return { value: totalCostUsd(byModel) };\n },\n };\n}\n\n/** stat → authoritative total tokens (input + output) over the range. */\nexport function agentTokensTotalProvider(): DataProvider {\n return {\n name: 'agent.spend.totalTokens',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { value: 0 };\n }\n const byModel = await queries.spendByModel(resolveRange(query));\n return { value: totalTokens(byModel) };\n },\n };\n}\n\n/** breakdown → spend share per model. */\nexport function agentSpendByModelProvider(): DataProvider {\n return {\n name: 'agent.spend.byModel',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { segments: [] };\n }\n const byModel = await queries.spendByModel(resolveRange(query));\n return { segments: toModelSpendSegments(byModel) };\n },\n };\n}\n\n/** table → per-model requests / in+out tokens / cost. */\nexport function agentModelSpendTableProvider(): DataProvider {\n return {\n name: 'agent.spend.byModelTable',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { rows: [] };\n }\n const byModel = await queries.spendByModel(resolveRange(query));\n return { rows: toModelSpendRows(byModel) };\n },\n };\n}\n\n/** timeseries → daily spend + tokens trend. */\nexport function agentUsageTrendProvider(): DataProvider {\n return {\n name: 'agent.usage.trend',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { rows: [] };\n }\n const trend = await queries.usageTrend(resolveRange(query));\n return { rows: toUsageTrendRows(trend) };\n },\n };\n}\n\n/** table → spend per acting ref (user/tenant). */\nexport function agentActorSpendTableProvider(): DataProvider {\n return {\n name: 'agent.spend.byActor',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { rows: [] };\n }\n const byActor = await queries.spendByActor(resolveRange(query));\n return { rows: toActorSpendRows(byActor) };\n },\n };\n}\n\n/** breakdown → spend share per actor. */\nexport function agentSpendByActorProvider(): DataProvider {\n return {\n name: 'agent.spend.byActorShare',\n async resolve(query, ctx) {\n const queries = resolveGovernanceQueries(ctx);\n if (!queries) {\n return { segments: [] };\n }\n const byActor = await queries.spendByActor(resolveRange(query));\n return { segments: toActorSpendSegments(byActor) };\n },\n };\n}\n","import { subscribe } from 'node:diagnostics_channel';\nimport { channelName } from '@dudousxd/nestjs-diagnostics';\nimport type { Watcher, WatcherContext } from '@dudousxd/nestjs-telescope';\n\nconst AGENT_EVENTS = ['run.started', 'message', 'tool-call', 'quota.exceeded', 'run.finished'];\n\ninterface DiagnosticEnvelope {\n event: string;\n payload: Record<string, unknown>;\n}\n\n/**\n * Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends\n * only on the diagnostics channel — not on the agent runtime — so it stays fully decoupled.\n */\nexport class AgentTelescopeWatcher implements Watcher {\n readonly type = 'agent';\n\n register(ctx: WatcherContext): void {\n for (const event of AGENT_EVENTS) {\n subscribe(channelName('agent', event), (message) => {\n const envelope = message as DiagnosticEnvelope;\n ctx.record({\n type: 'agent',\n content: { event: envelope.event, ...envelope.payload },\n tags: [envelope.event],\n });\n });\n }\n }\n}\n"],"mappings":"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","names":["import_nestjs_telescope","agentDashboard","id","label","panels","sections","title","cols","kind","data","provider","format","style","series","columns","key","fetchEntries","ctx","storage","moduleRef","get","TELESCOPE_STORAGE","strict","page","type","limit","data","ofEvent","entries","event","filter","entry","content","agentRunsProvider","name","resolve","_query","finished","value","length","agentTokensProvider","reduce","sum","inputTokens","outputTokens","agentToolsProvider","calls","slice","reverse","map","toolName","toolType","status","runId","rows","agentToolStatusProvider","counts","Map","call","set","segments","label","DEFAULT_TREND_WINDOW_DAYS","ISO_DAY_PATTERN","isRecord","value","isGovernanceQueries","spendByModel","spendByActor","usageTrend","recentToolCalls","recentThreads","resolveGovernanceQueries","ctx","resolved","moduleRef","get","AGENT_GOVERNANCE_QUERIES","strict","isIsoDay","test","todayUtcDay","Date","toISOString","slice","shiftUtcDay","day","deltaDays","shifted","setUTCDate","getUTCDate","resolveRange","query","toDay","fromDay","roundCents","Math","round","totalCostUsd","rows","reduce","sum","row","costUsd","totalTokens","inputTokens","outputTokens","toModelSpendSegments","filter","map","label","modelId","toModelSpendRows","requests","toActorSpendRows","actorRef","toActorSpendSegments","toUsageTrendRows","points","point","agentSpendTotalProvider","name","resolve","queries","byModel","agentTokensTotalProvider","agentSpendByModelProvider","segments","agentModelSpendTableProvider","agentUsageTrendProvider","trend","agentActorSpendTableProvider","byActor","agentSpendByActorProvider","AGENT_EVENTS","AgentTelescopeWatcher","type","register","ctx","event","subscribe","channelName","message","envelope","record","content","payload","tags","agentTelescopeExtension","defineTelescopeExtension","name","watchers","AgentTelescopeWatcher","entryTypes","id","label","dot","dashboards","agentDashboard","dataProviders","agentRunsProvider","agentTokensProvider","agentToolsProvider","agentToolStatusProvider","agentSpendTotalProvider","agentTokensTotalProvider","agentSpendByModelProvider","agentModelSpendTableProvider","agentUsageTrendProvider","agentActorSpendTableProvider","agentSpendByActorProvider"]}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
|
|
2
|
+
import { Watcher, WatcherContext, DashboardSpec, DataProvider } from '@dudousxd/nestjs-telescope';
|
|
3
|
+
import { GovernanceRange, ActorSpendRow, ModelSpendRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by two sources —
|
|
7
|
+
* the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, and the
|
|
8
|
+
* authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage) via the governance
|
|
9
|
+
* providers. The extension `name`, entry-type id, dashboard id, and every provider name share the
|
|
10
|
+
* `agent` prefix so the registry's global-uniqueness namespaces never collide with sibling extensions.
|
|
11
|
+
*
|
|
12
|
+
* Host wiring: the governance (Spend/Models/Actors) panels resolve `AGENT_GOVERNANCE_QUERIES` from
|
|
13
|
+
* the host DI container at request time (via `ctx.moduleRef`). The host must bind that token — from
|
|
14
|
+
* its store adapter (e.g. `store-mikro-orm` / `store-drizzle` / `testing`) — in the same module that
|
|
15
|
+
* registers `TelescopeModule.forRoot({ extensions: [agentTelescopeExtension()] })`. If the binding is
|
|
16
|
+
* absent, those panels render an empty state; the live watcher-fed panels keep working regardless.
|
|
17
|
+
*/
|
|
18
|
+
declare function agentTelescopeExtension(): _dudousxd_nestjs_telescope.TelescopeExtension;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends
|
|
22
|
+
* only on the diagnostics channel — not on the agent runtime — so it stays fully decoupled.
|
|
23
|
+
*/
|
|
24
|
+
declare class AgentTelescopeWatcher implements Watcher {
|
|
25
|
+
readonly type = "agent";
|
|
26
|
+
register(ctx: WatcherContext): void;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The "Agent" overview dashboard. Panels bind to the `agent.*` data providers. */
|
|
30
|
+
declare function agentDashboard(): DashboardSpec;
|
|
31
|
+
|
|
32
|
+
/** stat → total agent runs (run.finished entries). */
|
|
33
|
+
declare function agentRunsProvider(): DataProvider;
|
|
34
|
+
/** stat → total tokens across all finished runs. */
|
|
35
|
+
declare function agentTokensProvider(): DataProvider;
|
|
36
|
+
/** table → recent tool calls. */
|
|
37
|
+
declare function agentToolsProvider(): DataProvider;
|
|
38
|
+
/** breakdown → tool-call status distribution. */
|
|
39
|
+
declare function agentToolStatusProvider(): DataProvider;
|
|
40
|
+
|
|
41
|
+
/** A breakdown-panel segment (Telescope core: `{ segments: Array<{ label, value, color? }> }`). */
|
|
42
|
+
interface BreakdownSegment {
|
|
43
|
+
label: string;
|
|
44
|
+
value: number;
|
|
45
|
+
}
|
|
46
|
+
/** One row of the per-model usage/cost table. */
|
|
47
|
+
interface ModelSpendTableRow {
|
|
48
|
+
modelId: string;
|
|
49
|
+
requests: number;
|
|
50
|
+
inputTokens: number;
|
|
51
|
+
outputTokens: number;
|
|
52
|
+
costUsd: number;
|
|
53
|
+
}
|
|
54
|
+
/** One row of the per-actor spend table. */
|
|
55
|
+
interface ActorSpendTableRow {
|
|
56
|
+
actorRef: string;
|
|
57
|
+
requests: number;
|
|
58
|
+
totalTokens: number;
|
|
59
|
+
costUsd: number;
|
|
60
|
+
}
|
|
61
|
+
/** One point of the timeseries trend (Telescope core: `{ label } & Record<string, number>`). */
|
|
62
|
+
interface UsageTrendTableRow {
|
|
63
|
+
label: string;
|
|
64
|
+
costUsd: number;
|
|
65
|
+
totalTokens: number;
|
|
66
|
+
}
|
|
67
|
+
/** Shift a `YYYY-MM-DD` UTC day by `deltaDays` (negative goes back in time). */
|
|
68
|
+
declare function shiftUtcDay(day: string, deltaDays: number): string;
|
|
69
|
+
/**
|
|
70
|
+
* Derive the query range: honour explicit `fromDay`/`toDay` (validated ISO days), otherwise default
|
|
71
|
+
* to the trailing {@link DEFAULT_TREND_WINDOW_DAYS}-day window ending today (UTC).
|
|
72
|
+
*/
|
|
73
|
+
declare function resolveRange(query: Record<string, unknown> | undefined): GovernanceRange;
|
|
74
|
+
/** Sum authoritative spend across every model row. */
|
|
75
|
+
declare function totalCostUsd(rows: ModelSpendRow[]): number;
|
|
76
|
+
/** Sum input + output tokens across every model row. */
|
|
77
|
+
declare function totalTokens(rows: ModelSpendRow[]): number;
|
|
78
|
+
/** Spend-by-model as breakdown segments (models with zero cost are dropped from the donut). */
|
|
79
|
+
declare function toModelSpendSegments(rows: ModelSpendRow[]): BreakdownSegment[];
|
|
80
|
+
/** Spend-by-model as table rows (cost rounded to cents; usage kept exact). */
|
|
81
|
+
declare function toModelSpendRows(rows: ModelSpendRow[]): ModelSpendTableRow[];
|
|
82
|
+
/** Spend-by-actor as table rows. */
|
|
83
|
+
declare function toActorSpendRows(rows: ActorSpendRow[]): ActorSpendTableRow[];
|
|
84
|
+
/** Spend-by-actor as breakdown segments (actors with zero cost are dropped). */
|
|
85
|
+
declare function toActorSpendSegments(rows: ActorSpendRow[]): BreakdownSegment[];
|
|
86
|
+
/** Daily usage trend as timeseries rows keyed by `label` (the day). */
|
|
87
|
+
declare function toUsageTrendRows(points: UsageTrendPoint[]): UsageTrendTableRow[];
|
|
88
|
+
/** stat → authoritative total spend (USD) over the range. */
|
|
89
|
+
declare function agentSpendTotalProvider(): DataProvider;
|
|
90
|
+
/** stat → authoritative total tokens (input + output) over the range. */
|
|
91
|
+
declare function agentTokensTotalProvider(): DataProvider;
|
|
92
|
+
/** breakdown → spend share per model. */
|
|
93
|
+
declare function agentSpendByModelProvider(): DataProvider;
|
|
94
|
+
/** table → per-model requests / in+out tokens / cost. */
|
|
95
|
+
declare function agentModelSpendTableProvider(): DataProvider;
|
|
96
|
+
/** timeseries → daily spend + tokens trend. */
|
|
97
|
+
declare function agentUsageTrendProvider(): DataProvider;
|
|
98
|
+
/** table → spend per acting ref (user/tenant). */
|
|
99
|
+
declare function agentActorSpendTableProvider(): DataProvider;
|
|
100
|
+
/** breakdown → spend share per actor. */
|
|
101
|
+
declare function agentSpendByActorProvider(): DataProvider;
|
|
102
|
+
|
|
103
|
+
export { AgentTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentRunsProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatusProvider, agentToolsProvider, agentUsageTrendProvider, resolveRange, shiftUtcDay, toActorSpendRows, toActorSpendSegments, toModelSpendRows, toModelSpendSegments, toUsageTrendRows, totalCostUsd, totalTokens };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
import * as _dudousxd_nestjs_telescope from '@dudousxd/nestjs-telescope';
|
|
2
|
+
import { Watcher, WatcherContext, DashboardSpec, DataProvider } from '@dudousxd/nestjs-telescope';
|
|
3
|
+
import { GovernanceRange, ActorSpendRow, ModelSpendRow, UsageTrendPoint } from '@dudousxd/nestjs-agent-core';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The first-class Telescope extension for nestjs-agent: an "Agent" tab fed by two sources —
|
|
7
|
+
* the `aviary:agent:*` diagnostics channel (live runs, tool calls) via the watcher, and the
|
|
8
|
+
* authoritative `AGENT_GOVERNANCE_QUERIES` read-model (historical spend/usage) via the governance
|
|
9
|
+
* providers. The extension `name`, entry-type id, dashboard id, and every provider name share the
|
|
10
|
+
* `agent` prefix so the registry's global-uniqueness namespaces never collide with sibling extensions.
|
|
11
|
+
*
|
|
12
|
+
* Host wiring: the governance (Spend/Models/Actors) panels resolve `AGENT_GOVERNANCE_QUERIES` from
|
|
13
|
+
* the host DI container at request time (via `ctx.moduleRef`). The host must bind that token — from
|
|
14
|
+
* its store adapter (e.g. `store-mikro-orm` / `store-drizzle` / `testing`) — in the same module that
|
|
15
|
+
* registers `TelescopeModule.forRoot({ extensions: [agentTelescopeExtension()] })`. If the binding is
|
|
16
|
+
* absent, those panels render an empty state; the live watcher-fed panels keep working regardless.
|
|
17
|
+
*/
|
|
18
|
+
declare function agentTelescopeExtension(): _dudousxd_nestjs_telescope.TelescopeExtension;
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Records `aviary:agent:*` diagnostics events as Telescope entries of type `agent`. It depends
|
|
22
|
+
* only on the diagnostics channel — not on the agent runtime — so it stays fully decoupled.
|
|
23
|
+
*/
|
|
24
|
+
declare class AgentTelescopeWatcher implements Watcher {
|
|
25
|
+
readonly type = "agent";
|
|
26
|
+
register(ctx: WatcherContext): void;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The "Agent" overview dashboard. Panels bind to the `agent.*` data providers. */
|
|
30
|
+
declare function agentDashboard(): DashboardSpec;
|
|
31
|
+
|
|
32
|
+
/** stat → total agent runs (run.finished entries). */
|
|
33
|
+
declare function agentRunsProvider(): DataProvider;
|
|
34
|
+
/** stat → total tokens across all finished runs. */
|
|
35
|
+
declare function agentTokensProvider(): DataProvider;
|
|
36
|
+
/** table → recent tool calls. */
|
|
37
|
+
declare function agentToolsProvider(): DataProvider;
|
|
38
|
+
/** breakdown → tool-call status distribution. */
|
|
39
|
+
declare function agentToolStatusProvider(): DataProvider;
|
|
40
|
+
|
|
41
|
+
/** A breakdown-panel segment (Telescope core: `{ segments: Array<{ label, value, color? }> }`). */
|
|
42
|
+
interface BreakdownSegment {
|
|
43
|
+
label: string;
|
|
44
|
+
value: number;
|
|
45
|
+
}
|
|
46
|
+
/** One row of the per-model usage/cost table. */
|
|
47
|
+
interface ModelSpendTableRow {
|
|
48
|
+
modelId: string;
|
|
49
|
+
requests: number;
|
|
50
|
+
inputTokens: number;
|
|
51
|
+
outputTokens: number;
|
|
52
|
+
costUsd: number;
|
|
53
|
+
}
|
|
54
|
+
/** One row of the per-actor spend table. */
|
|
55
|
+
interface ActorSpendTableRow {
|
|
56
|
+
actorRef: string;
|
|
57
|
+
requests: number;
|
|
58
|
+
totalTokens: number;
|
|
59
|
+
costUsd: number;
|
|
60
|
+
}
|
|
61
|
+
/** One point of the timeseries trend (Telescope core: `{ label } & Record<string, number>`). */
|
|
62
|
+
interface UsageTrendTableRow {
|
|
63
|
+
label: string;
|
|
64
|
+
costUsd: number;
|
|
65
|
+
totalTokens: number;
|
|
66
|
+
}
|
|
67
|
+
/** Shift a `YYYY-MM-DD` UTC day by `deltaDays` (negative goes back in time). */
|
|
68
|
+
declare function shiftUtcDay(day: string, deltaDays: number): string;
|
|
69
|
+
/**
|
|
70
|
+
* Derive the query range: honour explicit `fromDay`/`toDay` (validated ISO days), otherwise default
|
|
71
|
+
* to the trailing {@link DEFAULT_TREND_WINDOW_DAYS}-day window ending today (UTC).
|
|
72
|
+
*/
|
|
73
|
+
declare function resolveRange(query: Record<string, unknown> | undefined): GovernanceRange;
|
|
74
|
+
/** Sum authoritative spend across every model row. */
|
|
75
|
+
declare function totalCostUsd(rows: ModelSpendRow[]): number;
|
|
76
|
+
/** Sum input + output tokens across every model row. */
|
|
77
|
+
declare function totalTokens(rows: ModelSpendRow[]): number;
|
|
78
|
+
/** Spend-by-model as breakdown segments (models with zero cost are dropped from the donut). */
|
|
79
|
+
declare function toModelSpendSegments(rows: ModelSpendRow[]): BreakdownSegment[];
|
|
80
|
+
/** Spend-by-model as table rows (cost rounded to cents; usage kept exact). */
|
|
81
|
+
declare function toModelSpendRows(rows: ModelSpendRow[]): ModelSpendTableRow[];
|
|
82
|
+
/** Spend-by-actor as table rows. */
|
|
83
|
+
declare function toActorSpendRows(rows: ActorSpendRow[]): ActorSpendTableRow[];
|
|
84
|
+
/** Spend-by-actor as breakdown segments (actors with zero cost are dropped). */
|
|
85
|
+
declare function toActorSpendSegments(rows: ActorSpendRow[]): BreakdownSegment[];
|
|
86
|
+
/** Daily usage trend as timeseries rows keyed by `label` (the day). */
|
|
87
|
+
declare function toUsageTrendRows(points: UsageTrendPoint[]): UsageTrendTableRow[];
|
|
88
|
+
/** stat → authoritative total spend (USD) over the range. */
|
|
89
|
+
declare function agentSpendTotalProvider(): DataProvider;
|
|
90
|
+
/** stat → authoritative total tokens (input + output) over the range. */
|
|
91
|
+
declare function agentTokensTotalProvider(): DataProvider;
|
|
92
|
+
/** breakdown → spend share per model. */
|
|
93
|
+
declare function agentSpendByModelProvider(): DataProvider;
|
|
94
|
+
/** table → per-model requests / in+out tokens / cost. */
|
|
95
|
+
declare function agentModelSpendTableProvider(): DataProvider;
|
|
96
|
+
/** timeseries → daily spend + tokens trend. */
|
|
97
|
+
declare function agentUsageTrendProvider(): DataProvider;
|
|
98
|
+
/** table → spend per acting ref (user/tenant). */
|
|
99
|
+
declare function agentActorSpendTableProvider(): DataProvider;
|
|
100
|
+
/** breakdown → spend share per actor. */
|
|
101
|
+
declare function agentSpendByActorProvider(): DataProvider;
|
|
102
|
+
|
|
103
|
+
export { AgentTelescopeWatcher, agentActorSpendTableProvider, agentDashboard, agentModelSpendTableProvider, agentRunsProvider, agentSpendByActorProvider, agentSpendByModelProvider, agentSpendTotalProvider, agentTelescopeExtension, agentTokensProvider, agentTokensTotalProvider, agentToolStatusProvider, agentToolsProvider, agentUsageTrendProvider, resolveRange, shiftUtcDay, toActorSpendRows, toActorSpendSegments, toModelSpendRows, toModelSpendSegments, toUsageTrendRows, totalCostUsd, totalTokens };
|