@dudousxd/nestjs-agent-core 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
 interface Actor {
@@ -119,6 +120,11 @@ interface QuotaView {
 interface Decision {
     approved: boolean;
     reason?: string;
+    /**
+     * Opaque ref of WHO decided (e.g. a console admin). When absent, the run's own actor decided
+     * (the chat flow).
+     */
+    executedByRef?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
 /**
@@ -357,6 +363,11 @@ declare const AGENT_ACTOR_DIRECTORY: unique symbol;
  * {@link import('./spi/attachment-staging.js').AttachmentStagingStore}.
  */
 declare const AGENT_ATTACHMENT_STAGING: unique symbol;
+/**
+ * Console-side HITL approve/reject for the cross-thread approvals inbox. Optional — see
+ * {@link import('./spi/approval-port.js').AgentApprovalPort}.
+ */
+declare const AGENT_APPROVAL_PORT: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -578,6 +589,8 @@ interface RecordRunStartInput {
     threadId: string;
     actorRef: string;
     agentName?: string;
+    /** sha256 hex of the run's resolved (pre-RAG) system prompt — identifies the prompt VERSION. */
+    promptHash?: string;
 }
 interface RecordRunEndInput {
     runId: string;
@@ -921,6 +934,31 @@ interface RecentRunRow {
     retries: number;
     /** ISO timestamp. */
     startedAt: string;
+    /** sha256 hex of the run's resolved (pre-RAG) system prompt; `null` for a run recorded before this shipped. */
+    promptHash: string | null;
+}
+/** One tool call awaiting a HITL decision, for the cross-thread approvals inbox. */
+interface PendingApprovalRow {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    threadId: string;
+    threadTitle: string;
+    /** Who asked — the run's actor. */
+    actorRef: string;
+    agentName: string | null;
+    /** ISO timestamp. */
+    requestedAt: string;
+}
+/** Governance rollup for one tool over a range. */
+interface ToolStatRow {
+    toolName: string;
+    toolType: string;
+    calls: number;
+    failed: number;
+    rejected: number;
+    /** p95 of executionMs across executed calls; null when none carry it. */
+    p95ExecutionMs: number | null;
 }
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
@@ -940,6 +978,10 @@ interface AgentGovernanceQueries {
     runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
     runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
     recentRuns(limit: number): Promise<RecentRunRow[]>;
+    /** Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at `limit`. */
+    pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
+    /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
+    toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
 }
 
 /**
@@ -981,6 +1023,21 @@ interface AttachmentStagingStore {
     stage(input: StageAttachmentInput): Promise<MessageAttachment>;
 }
 
+/**
+ * Console-side HITL decisions. Implemented by the agent runtime (the nestjs package binds it to
+ * the same signal path chat approvals use); the dashboard injects it OPTIONALLY — absent = the
+ * approvals inbox renders read-only.
+ */
+interface AgentApprovalPort {
+    approve(toolCallId: string, opts?: {
+        executedByRef?: string;
+    }): Promise<void>;
+    reject(toolCallId: string, opts?: {
+        executedByRef?: string;
+        reason?: string;
+    }): Promise<void>;
+}
+
 /**
  * The pure aggregation core shared by every {@link import('../spi/governance-queries.js').AgentGovernanceQueries}
  * adapter (MikroORM, Drizzle, in-memory). An adapter's only job is the DB-specific row fetch; the
@@ -1201,6 +1258,22 @@ declare class QuotaExceededError extends Error {
 }
 /** Reject if `work` doesn't settle within `ms`. The underlying work is left to finish on its own. */
 declare function withToolTimeout<T>(work: Promise<T>, ms: number, toolName: string): Promise<T>;
+/**
+ * Span-wrap one model call (`aviary:agent:llm.turn`). Exported so the durable dispatched-step
+ * handler (which executes the genuine remote llm step) can emit the same span — core cannot wrap
+ * `hooks.dispatchLlm` itself, because that call also runs (from cache) on replay.
+ */
+declare function traceLlmTurn(runId: string, step: number, run: () => Promise<ModelTurnResult>): Promise<ModelTurnResult>;
+/**
+ * Span-wrap one tool invocation (`aviary:agent:tool.execution`). The tool's raw output never
+ * rides the span (only the start payload's name/type metadata + duration). Exported for the
+ * durable dispatched-step handler, like {@link traceLlmTurn}.
+ */
+declare function traceToolExecution<T>(runId: string, call: {
+    toolCallId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+}, run: () => Promise<T>): Promise<T>;
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
@@ -1260,7 +1333,35 @@ interface AgentRetrieved {
     /** How many passages the retriever returned. */
     count: number;
 }
-/** Declaration-merge so `emit('agent', ...)` and telescope infer the agent payloads. */
+/** START payload of an `aviary:agent:llm.turn:*` span — one model call within a run. */
+interface AgentLlmTurnSpan {
+    runId: string;
+    /** Zero-based model-call index within the run (the loop's step counter). */
+    step: number;
+}
+/** START payload of an `aviary:agent:tool.execution:*` span — one tool invocation. */
+interface AgentToolExecutionSpan {
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+}
+/** START payload of an `aviary:agent:retrieval:*` span — inject-mode RAG retrieval. */
+interface AgentRetrievalSpan {
+    runId: string;
+    /** Length of the retrieval query in characters — never the query text itself. */
+    queryLength: number;
+    topK: number;
+}
+/** START payload of an `aviary:agent:follow-ups:*` span — the extra follow-up-suggestions call. */
+interface AgentFollowUpsSpan {
+    runId: string;
+    /** Zero-based model-call index of the final turn the follow-ups ride on. */
+    step: number;
+    /** How many follow-up questions were requested. */
+    count: number;
+}
+/** Declaration-merge so `emit('agent', ...)`, `trace('agent', ...)` and telescope infer the agent payloads. */
 declare module '@dudousxd/nestjs-diagnostics' {
     interface ChannelRegistry {
         agent: {
@@ -1272,6 +1373,10 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'llm.turn': AgentLlmTurnSpan;
+            'tool.execution': AgentToolExecutionSpan;
+            retrieval: AgentRetrievalSpan;
+            'follow-ups': AgentFollowUpsSpan;
         };
     }
 }
@@ -1283,5 +1388,39 @@ declare function publishAgentRunFinished(payload: AgentRunFinished): void;
 declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
+/**
+ * Events published ONLY as spans — via `trace('agent', ...)` on the five `:start`/`:end`/
+ * `:asyncStart`/`:asyncEnd`/`:error` sub-channels — never as point events on the base channel.
+ * They are deliberately NOT in {@link AGENT_DIAGNOSTIC_EVENTS}: the point-event watcher has
+ * nothing to subscribe to on their base channels, and claiming their keys would be meaningless
+ * (the generic bridge only records point traffic).
+ */
+type AgentSpanEvent = 'llm.turn' | 'tool.execution' | 'retrieval' | 'follow-ups';
+/** All span-only events, in a stable order — for a future span recorder to derive sub-channels from. */
+declare const AGENT_SPAN_EVENTS: readonly AgentSpanEvent[];
+/** Every POINT event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
+type AgentDiagnosticEvent = Exclude<keyof ChannelRegistry['agent'], AgentSpanEvent>;
+/**
+ * All 8 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
+ * subscribers (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). Span-only events (see
+ * {@link AgentSpanEvent}) are excluded. A drift between this list and the registry is a compile
+ * error in both directions: an extra/misspelled entry fails this array's own
+ * `readonly AgentDiagnosticEvent[]` annotation immediately; a missing entry fails the
+ * {@link AgentDiagnosticEventsCoverAllKeys} check below.
+ */
+declare const AGENT_DIAGNOSTIC_EVENTS: readonly AgentDiagnosticEvent[];
+/**
+ * The telescope key for an agent diagnostics channel — `agent:<event>`. This is the key the
+ * `@dudousxd/nestjs-diagnostics-telescope` generic bridge matches its `exclude` option against,
+ * and the label its "Busiest events" panel shows. Distinct from the `aviary:agent:<event>` channel
+ * name used on the wire. Mirrors `mediaDiagnosticKey`.
+ */
+type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
+/**
+ * Compose the telescope key for an agent event, typed against {@link AgentDiagnosticEvent} so a
+ * misspelled event is a compile error. Feed the result to `nestjsDiagnosticsTelescope({ exclude:
+ * [...] })` to mute a noisy channel, e.g. `agentDiagnosticKey('message')`.
+ */
+declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, withToolTimeout };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, withToolTimeout };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { StandardSchemaV1 } from '@standard-schema/spec';
+import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
 /** Who is driving the turn. Roles + tenant come from the host app (nestjs-context/authz). */
 interface Actor {
@@ -119,6 +120,11 @@ interface QuotaView {
 interface Decision {
     approved: boolean;
     reason?: string;
+    /**
+     * Opaque ref of WHO decided (e.g. a console admin). When absent, the run's own actor decided
+     * (the chat flow).
+     */
+    executedByRef?: string;
 }
 type MessageRole = 'user' | 'assistant' | 'system';
 /**
@@ -357,6 +363,11 @@ declare const AGENT_ACTOR_DIRECTORY: unique symbol;
  * {@link import('./spi/attachment-staging.js').AttachmentStagingStore}.
  */
 declare const AGENT_ATTACHMENT_STAGING: unique symbol;
+/**
+ * Console-side HITL approve/reject for the cross-thread approvals inbox. Optional — see
+ * {@link import('./spi/approval-port.js').AgentApprovalPort}.
+ */
+declare const AGENT_APPROVAL_PORT: unique symbol;
 
 /**
  * Per-invocation context handed to a tool handler. Host-supplied bits are optional. Identity lives
@@ -578,6 +589,8 @@ interface RecordRunStartInput {
     threadId: string;
     actorRef: string;
     agentName?: string;
+    /** sha256 hex of the run's resolved (pre-RAG) system prompt — identifies the prompt VERSION. */
+    promptHash?: string;
 }
 interface RecordRunEndInput {
     runId: string;
@@ -921,6 +934,31 @@ interface RecentRunRow {
     retries: number;
     /** ISO timestamp. */
     startedAt: string;
+    /** sha256 hex of the run's resolved (pre-RAG) system prompt; `null` for a run recorded before this shipped. */
+    promptHash: string | null;
+}
+/** One tool call awaiting a HITL decision, for the cross-thread approvals inbox. */
+interface PendingApprovalRow {
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+    threadId: string;
+    threadTitle: string;
+    /** Who asked — the run's actor. */
+    actorRef: string;
+    agentName: string | null;
+    /** ISO timestamp. */
+    requestedAt: string;
+}
+/** Governance rollup for one tool over a range. */
+interface ToolStatRow {
+    toolName: string;
+    toolType: string;
+    calls: number;
+    failed: number;
+    rejected: number;
+    /** p95 of executionMs across executed calls; null when none carry it. */
+    p95ExecutionMs: number | null;
 }
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
@@ -940,6 +978,10 @@ interface AgentGovernanceQueries {
     runErrors(range: GovernanceRange): Promise<RunErrorBreakdownRow[]>;
     runTrend(range: GovernanceRange): Promise<RunTrendPoint[]>;
     recentRuns(limit: number): Promise<RecentRunRow[]>;
+    /** Tool calls sitting `pending_approval`, oldest first — an inbox drains from the back. Capped at `limit`. */
+    pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
+    /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
+    toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
 }
 
 /**
@@ -981,6 +1023,21 @@ interface AttachmentStagingStore {
     stage(input: StageAttachmentInput): Promise<MessageAttachment>;
 }
 
+/**
+ * Console-side HITL decisions. Implemented by the agent runtime (the nestjs package binds it to
+ * the same signal path chat approvals use); the dashboard injects it OPTIONALLY — absent = the
+ * approvals inbox renders read-only.
+ */
+interface AgentApprovalPort {
+    approve(toolCallId: string, opts?: {
+        executedByRef?: string;
+    }): Promise<void>;
+    reject(toolCallId: string, opts?: {
+        executedByRef?: string;
+        reason?: string;
+    }): Promise<void>;
+}
+
 /**
  * The pure aggregation core shared by every {@link import('../spi/governance-queries.js').AgentGovernanceQueries}
  * adapter (MikroORM, Drizzle, in-memory). An adapter's only job is the DB-specific row fetch; the
@@ -1201,6 +1258,22 @@ declare class QuotaExceededError extends Error {
 }
 /** Reject if `work` doesn't settle within `ms`. The underlying work is left to finish on its own. */
 declare function withToolTimeout<T>(work: Promise<T>, ms: number, toolName: string): Promise<T>;
+/**
+ * Span-wrap one model call (`aviary:agent:llm.turn`). Exported so the durable dispatched-step
+ * handler (which executes the genuine remote llm step) can emit the same span — core cannot wrap
+ * `hooks.dispatchLlm` itself, because that call also runs (from cache) on replay.
+ */
+declare function traceLlmTurn(runId: string, step: number, run: () => Promise<ModelTurnResult>): Promise<ModelTurnResult>;
+/**
+ * Span-wrap one tool invocation (`aviary:agent:tool.execution`). The tool's raw output never
+ * rides the span (only the start payload's name/type metadata + duration). Exported for the
+ * durable dispatched-step handler, like {@link traceLlmTurn}.
+ */
+declare function traceToolExecution<T>(runId: string, call: {
+    toolCallId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+}, run: () => Promise<T>): Promise<T>;
 /**
  * The provider-agnostic agent turn, reused by both the inline and durable runners.
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
@@ -1260,7 +1333,35 @@ interface AgentRetrieved {
     /** How many passages the retriever returned. */
     count: number;
 }
-/** Declaration-merge so `emit('agent', ...)` and telescope infer the agent payloads. */
+/** START payload of an `aviary:agent:llm.turn:*` span — one model call within a run. */
+interface AgentLlmTurnSpan {
+    runId: string;
+    /** Zero-based model-call index within the run (the loop's step counter). */
+    step: number;
+}
+/** START payload of an `aviary:agent:tool.execution:*` span — one tool invocation. */
+interface AgentToolExecutionSpan {
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    toolType: 'read' | 'action';
+}
+/** START payload of an `aviary:agent:retrieval:*` span — inject-mode RAG retrieval. */
+interface AgentRetrievalSpan {
+    runId: string;
+    /** Length of the retrieval query in characters — never the query text itself. */
+    queryLength: number;
+    topK: number;
+}
+/** START payload of an `aviary:agent:follow-ups:*` span — the extra follow-up-suggestions call. */
+interface AgentFollowUpsSpan {
+    runId: string;
+    /** Zero-based model-call index of the final turn the follow-ups ride on. */
+    step: number;
+    /** How many follow-up questions were requested. */
+    count: number;
+}
+/** Declaration-merge so `emit('agent', ...)`, `trace('agent', ...)` and telescope infer the agent payloads. */
 declare module '@dudousxd/nestjs-diagnostics' {
     interface ChannelRegistry {
         agent: {
@@ -1272,6 +1373,10 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'llm.turn': AgentLlmTurnSpan;
+            'tool.execution': AgentToolExecutionSpan;
+            retrieval: AgentRetrievalSpan;
+            'follow-ups': AgentFollowUpsSpan;
         };
     }
 }
@@ -1283,5 +1388,39 @@ declare function publishAgentRunFinished(payload: AgentRunFinished): void;
 declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
+/**
+ * Events published ONLY as spans — via `trace('agent', ...)` on the five `:start`/`:end`/
+ * `:asyncStart`/`:asyncEnd`/`:error` sub-channels — never as point events on the base channel.
+ * They are deliberately NOT in {@link AGENT_DIAGNOSTIC_EVENTS}: the point-event watcher has
+ * nothing to subscribe to on their base channels, and claiming their keys would be meaningless
+ * (the generic bridge only records point traffic).
+ */
+type AgentSpanEvent = 'llm.turn' | 'tool.execution' | 'retrieval' | 'follow-ups';
+/** All span-only events, in a stable order — for a future span recorder to derive sub-channels from. */
+declare const AGENT_SPAN_EVENTS: readonly AgentSpanEvent[];
+/** Every POINT event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
+type AgentDiagnosticEvent = Exclude<keyof ChannelRegistry['agent'], AgentSpanEvent>;
+/**
+ * All 8 point events on `ChannelRegistry['agent']`, in a stable order — handy for wiring
+ * subscribers (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). Span-only events (see
+ * {@link AgentSpanEvent}) are excluded. A drift between this list and the registry is a compile
+ * error in both directions: an extra/misspelled entry fails this array's own
+ * `readonly AgentDiagnosticEvent[]` annotation immediately; a missing entry fails the
+ * {@link AgentDiagnosticEventsCoverAllKeys} check below.
+ */
+declare const AGENT_DIAGNOSTIC_EVENTS: readonly AgentDiagnosticEvent[];
+/**
+ * The telescope key for an agent diagnostics channel — `agent:<event>`. This is the key the
+ * `@dudousxd/nestjs-diagnostics-telescope` generic bridge matches its `exclude` option against,
+ * and the label its "Busiest events" panel shows. Distinct from the `aviary:agent:<event>` channel
+ * name used on the wire. Mirrors `mediaDiagnosticKey`.
+ */
+type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
+/**
+ * Compose the telescope key for an agent event, typed against {@link AgentDiagnosticEvent} so a
+ * misspelled event is a compile error. Feed the result to `nestjsDiagnosticsTelescope({ exclude:
+ * [...] })` to mute a noisy channel, e.g. `agentDiagnosticKey('message')`.
+ */
+declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentGovernanceQueries, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, withToolTimeout };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, type Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, type AgentCatalogEntry, type AgentDefinition, type AgentDelegated, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, type AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSpanEvent, type AgentStore, AgentStreamError, type AgentStreamEvent, type AgentToolCallEvent, type AgentToolExecutionSpan, type AiToolCtx, type AppendMessageInput, type AttachmentStagingStore, type CostUsage, type CreateThreadInput, type CurrentModelPrice, type Decision, DefaultRolesPolicy, type EmbeddingProvider, type GovernanceRange, type GovernanceUsageInput, type LlmStepEnvelope, type MessageAttachment, type MessageRole, type MessageUsage, type ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type PageContext, type Passage, type PendingApprovalRow, type PromptBuilder, type PromptContext, type PromptContributor, QuotaExceededError, type QuotaState, type QuotaStore, type QuotaView, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RerankOptions, type Reranker, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, type RunErrorBreakdownRow, type RunMetrics, type RunTrendPoint, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolDefinition, ToolForbiddenError, type ToolHandler, ToolInputInvalidError, type ToolKind, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolSpec, type ToolStatRow, type ToolStepCtx, type ToolStepEnvelope, type UpdateThreadInput, type UpdateToolCallInput, type UsagePurpose, type UsageTrendPoint, agentDiagnosticKey, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, dayBoundsUtc, encodeStreamEvent, estimateCost, filterToolsByAllowList, filterToolsByRole, publishAgentDelegated, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentToolCall, runAgentLoop, seedModelPrices, traceLlmTurn, traceToolExecution, withToolTimeout };