@dudousxd/nestjs-agent-core 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -960,6 +960,53 @@ interface ToolStatRow {
     /** p95 of executionMs across executed calls; null when none carry it. */
     p95ExecutionMs: number | null;
 }
+/**
+ * Neutral paged query for the governance list reads (`toolCallsPage`/`threadsPage`/`runsPage`). The
+ * WIRE format a host exposes over HTTP mirrors `@dudousxd/nestjs-filter`'s conventions (`page`,
+ * `limit`, `where[field][op]`) so consumers see one grammar across the ecosystem, but this SPI stays
+ * neutral/typed — no filter-builder or ORM coupling here.
+ */
+interface GovernancePageQuery<TWhere> {
+    /** 1-based. */
+    page: number;
+    /** Rows per page, already clamped by the caller (the dashboard clamps to 200). */
+    pageSize: number;
+    /** Equality/range filters; absent field = no constraint. */
+    where?: TWhere;
+}
+/** One page of a governance list read, with the total row count for prev/next + "page X of Y" UI. */
+interface GovernancePage<TRow> {
+    rows: TRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** Filters for {@link AgentGovernanceQueries.toolCallsPage}. */
+interface ToolCallWhere {
+    toolName?: string;
+    toolType?: string;
+    status?: string;
+    threadId?: string;
+    /** Inclusive UTC day bounds, `YYYY-MM-DD`. */
+    fromDay?: string;
+    toDay?: string;
+}
+/** Filters for {@link AgentGovernanceQueries.threadsPage}. */
+interface ThreadWhere {
+    actorRef?: string;
+    /** Substring match on the title (case-insensitive). */
+    title?: string;
+    fromDay?: string;
+    toDay?: string;
+}
+/** Filters for {@link AgentGovernanceQueries.runsPage}. */
+interface RunWhere {
+    agentName?: string;
+    status?: string;
+    errorCode?: string;
+    fromDay?: string;
+    toDay?: string;
+}
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -982,6 +1029,21 @@ interface AgentGovernanceQueries {
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
     /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
     toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
+    /**
+     * Paged, filterable tool-call activity, newest-first (same ordering as `recentToolCalls`). An
+     * adapter without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    toolCallsPage(query: GovernancePageQuery<ToolCallWhere>): Promise<GovernancePage<ToolCallActivityRow>>;
+    /**
+     * Paged, filterable thread activity, newest-first (same ordering as `recentThreads`). An adapter
+     * without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    threadsPage(query: GovernancePageQuery<ThreadWhere>): Promise<GovernancePage<ThreadActivityRow>>;
+    /**
+     * Paged, filterable run activity, newest-first (same ordering as `recentRuns`). An adapter backed
+     * by a store without run recording (no `recordRunStart`) returns an empty page (`total: 0`).
+     */
+    runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
 }
 
 /**
@@ -1258,6 +1320,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`
@@ -1317,7 +1395,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: {
@@ -1329,6 +1435,10 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'llm.turn': AgentLlmTurnSpan;
+            'tool.execution': AgentToolExecutionSpan;
+            retrieval: AgentRetrievalSpan;
+            'follow-ups': AgentFollowUpsSpan;
         };
     }
 }
@@ -1340,12 +1450,23 @@ declare function publishAgentRunFinished(payload: AgentRunFinished): void;
 declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
-/** Every event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
-type AgentDiagnosticEvent = keyof ChannelRegistry['agent'];
 /**
- * All 8 events on `ChannelRegistry['agent']`, in a stable order — handy for wiring subscribers
- * (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). A drift between this list and the registry is
- * a compile error in both directions: an extra/misspelled entry fails this array's own
+ * 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.
  */
@@ -1364,4 +1485,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-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_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 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 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, 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 GovernancePage, type GovernancePageQuery, 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 RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, 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

@@ -960,6 +960,53 @@ interface ToolStatRow {
     /** p95 of executionMs across executed calls; null when none carry it. */
     p95ExecutionMs: number | null;
 }
+/**
+ * Neutral paged query for the governance list reads (`toolCallsPage`/`threadsPage`/`runsPage`). The
+ * WIRE format a host exposes over HTTP mirrors `@dudousxd/nestjs-filter`'s conventions (`page`,
+ * `limit`, `where[field][op]`) so consumers see one grammar across the ecosystem, but this SPI stays
+ * neutral/typed — no filter-builder or ORM coupling here.
+ */
+interface GovernancePageQuery<TWhere> {
+    /** 1-based. */
+    page: number;
+    /** Rows per page, already clamped by the caller (the dashboard clamps to 200). */
+    pageSize: number;
+    /** Equality/range filters; absent field = no constraint. */
+    where?: TWhere;
+}
+/** One page of a governance list read, with the total row count for prev/next + "page X of Y" UI. */
+interface GovernancePage<TRow> {
+    rows: TRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/** Filters for {@link AgentGovernanceQueries.toolCallsPage}. */
+interface ToolCallWhere {
+    toolName?: string;
+    toolType?: string;
+    status?: string;
+    threadId?: string;
+    /** Inclusive UTC day bounds, `YYYY-MM-DD`. */
+    fromDay?: string;
+    toDay?: string;
+}
+/** Filters for {@link AgentGovernanceQueries.threadsPage}. */
+interface ThreadWhere {
+    actorRef?: string;
+    /** Substring match on the title (case-insensitive). */
+    title?: string;
+    fromDay?: string;
+    toDay?: string;
+}
+/** Filters for {@link AgentGovernanceQueries.runsPage}. */
+interface RunWhere {
+    agentName?: string;
+    status?: string;
+    errorCode?: string;
+    fromDay?: string;
+    toDay?: string;
+}
 /**
  * The governance read-model. Cost is `inputTokens/1e6 * inputPricePer1m + outputTokens/1e6 *
  * outputPricePer1m` against the current pricing row per model; an unpriced model contributes 0 cost
@@ -982,6 +1029,21 @@ interface AgentGovernanceQueries {
     pendingApprovals(limit: number): Promise<PendingApprovalRow[]>;
     /** Per-tool call/failure/rejection/latency rollup over the range, highest call count first. */
     toolStats(range: GovernanceRange): Promise<ToolStatRow[]>;
+    /**
+     * Paged, filterable tool-call activity, newest-first (same ordering as `recentToolCalls`). An
+     * adapter without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    toolCallsPage(query: GovernancePageQuery<ToolCallWhere>): Promise<GovernancePage<ToolCallActivityRow>>;
+    /**
+     * Paged, filterable thread activity, newest-first (same ordering as `recentThreads`). An adapter
+     * without the backing data returns an empty page (`total: 0`) rather than throwing.
+     */
+    threadsPage(query: GovernancePageQuery<ThreadWhere>): Promise<GovernancePage<ThreadActivityRow>>;
+    /**
+     * Paged, filterable run activity, newest-first (same ordering as `recentRuns`). An adapter backed
+     * by a store without run recording (no `recordRunStart`) returns an empty page (`total: 0`).
+     */
+    runsPage(query: GovernancePageQuery<RunWhere>): Promise<GovernancePage<RecentRunRow>>;
 }
 
 /**
@@ -1258,6 +1320,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`
@@ -1317,7 +1395,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: {
@@ -1329,6 +1435,10 @@ declare module '@dudousxd/nestjs-diagnostics' {
             'run.failed': AgentRunFailed;
             delegated: AgentDelegated;
             retrieved: AgentRetrieved;
+            'llm.turn': AgentLlmTurnSpan;
+            'tool.execution': AgentToolExecutionSpan;
+            retrieval: AgentRetrievalSpan;
+            'follow-ups': AgentFollowUpsSpan;
         };
     }
 }
@@ -1340,12 +1450,23 @@ declare function publishAgentRunFinished(payload: AgentRunFinished): void;
 declare function publishAgentRunFailed(payload: AgentRunFailed): void;
 declare function publishAgentDelegated(payload: AgentDelegated): void;
 declare function publishAgentRetrieved(payload: AgentRetrieved): void;
-/** Every event key declared on `ChannelRegistry['agent']` above — derived, not hand-copied. */
-type AgentDiagnosticEvent = keyof ChannelRegistry['agent'];
 /**
- * All 8 events on `ChannelRegistry['agent']`, in a stable order — handy for wiring subscribers
- * (mirrors nestjs-media's `MEDIA_DIAGNOSTIC_EVENTS`). A drift between this list and the registry is
- * a compile error in both directions: an extra/misspelled entry fails this array's own
+ * 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.
  */
@@ -1364,4 +1485,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-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_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 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 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, 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 GovernancePage, type GovernancePageQuery, 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 RunWhere, type SinkWriter, type StageAttachmentInput, type StoredMessage, type StreamError, type ThreadActivityRow, type ThreadDetail, type ThreadMeta, type ThreadSpendRow, type ThreadSummary, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, type ToolCallRequest, type ToolCallStatus, type ToolCallWhere, 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.js

@@ -327,6 +327,7 @@ var DefaultRolesPolicy = class {
 
 // src/agent-loop.ts
 import { createHash } from "node:crypto";
+import { trace } from "@dudousxd/nestjs-diagnostics";
 
 // src/diagnostics.ts
 import { emit } from "@dudousxd/nestjs-diagnostics";
@@ -362,6 +363,12 @@ function publishAgentRetrieved(payload) {
   emit("agent", "retrieved", payload);
 }
 __name(publishAgentRetrieved, "publishAgentRetrieved");
+var AGENT_SPAN_EVENTS = [
+  "llm.turn",
+  "tool.execution",
+  "retrieval",
+  "follow-ups"
+];
 var AGENT_DIAGNOSTIC_EVENTS = [
   "run.started",
   "message",
@@ -503,6 +510,39 @@ async function generateFollowUps(model, messages, count) {
   };
 }
 __name(generateFollowUps, "generateFollowUps");
+async function spanned(event, runId, payload, run, summarize) {
+  let value;
+  await trace("agent", event, async () => {
+    value = await run();
+    return summarize(value);
+  }, payload, {
+    traceId: runId
+  });
+  return value;
+}
+__name(spanned, "spanned");
+function traceLlmTurn(runId, step, run) {
+  return spanned("llm.turn", runId, {
+    runId,
+    step
+  }, run, (turn) => ({
+    ...turn.modelId !== void 0 ? {
+      modelId: turn.modelId
+    } : {},
+    inputTokens: turn.usage.inputTokens,
+    outputTokens: turn.usage.outputTokens,
+    textLength: turn.text.length,
+    toolCalls: turn.toolCalls.length
+  }));
+}
+__name(traceLlmTurn, "traceLlmTurn");
+function traceToolExecution(runId, call, run) {
+  return spanned("tool.execution", runId, {
+    runId,
+    ...call
+  }, run, () => ({}));
+}
+__name(traceToolExecution, "traceToolExecution");
 async function runAgentLoop(deps, input, hooks) {
   const maxSteps = deps.maxSteps ?? 8;
   let system = await resolveSystemPrompt(deps, input);
@@ -587,9 +627,16 @@ async function runAgentLoop(deps, input, hooks) {
   let injectedPassages;
   if (deps.retriever !== void 0) {
     const retriever = deps.retriever;
-    const passages = await hooks.step("retrieve", () => retriever.retrieve(input.userText, {
-      topK: deps.retrievalTopK ?? 5
-    }));
+    const topK = deps.retrievalTopK ?? 5;
+    const passages = await hooks.step("retrieve", () => spanned("retrieval", hooks.runId, {
+      runId: hooks.runId,
+      queryLength: input.userText.length,
+      topK
+    }, () => retriever.retrieve(input.userText, {
+      topK
+    }), (retrieved) => ({
+      count: retrieved.length
+    })));
     if (passages.length > 0) {
       injectedPassages = passages;
       system = `${system}
@@ -629,12 +676,12 @@ ${buildContextBlock(passages)}`;
       });
     } else {
       const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
-      turn = await hooks.step(`llm:${i}`, () => deps.model.runTurn({
+      turn = await hooks.step(`llm:${i}`, () => traceLlmTurn(hooks.runId, i, () => deps.model.runTurn({
         system,
         messages: modelMessages,
         tools,
         sink: writer
-      }));
+      })));
     }
     const resolvedModelId = turn.modelId ?? deps.modelId ?? "unknown";
     const costUsd = resolveCostUsd(turn.usage, turn.costUsd, priceByModel.get(resolvedModelId));
@@ -671,13 +718,24 @@ ${buildContextBlock(passages)}`;
     let followUps;
     if (isFinalTurn && deps.followUpsCount !== void 0 && deps.followUpsCount > 0) {
       const count = deps.followUpsCount;
-      const generated = await hooks.step(`followups:${i}`, () => generateFollowUps(deps.model, [
+      const generated = await hooks.step(`followups:${i}`, () => spanned("follow-ups", hooks.runId, {
+        runId: hooks.runId,
+        step: i,
+        count
+      }, () => generateFollowUps(deps.model, [
         ...modelMessages,
         {
           role: "assistant",
           content: turn.text
         }
-      ], count));
+      ], count), (result) => ({
+        followUps: result.followUps.length,
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens,
+        ...result.modelId !== void 0 ? {
+          modelId: result.modelId
+        } : {}
+      })));
       if (generated.followUps.length > 0) {
         followUps = generated.followUps;
       }
@@ -884,7 +942,11 @@ ${buildContextBlock(passages)}`;
           };
           output = await hooks.dispatchTool(call, envelope);
         } else {
-          const invocation = hooks.step(`tool:${call.id}`, () => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy));
+          const invocation = hooks.step(`tool:${call.id}`, () => traceToolExecution(hooks.runId, {
+            toolCallId: call.id,
+            toolName: call.name,
+            toolType
+          }, () => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy)));
           output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
         }
         const executionMs = Date.now() - startedAt2;
@@ -1001,6 +1063,7 @@ export {
   AGENT_ROLES_POLICY,
   AGENT_RUNNER,
   AGENT_SINK,
+  AGENT_SPAN_EVENTS,
   AGENT_STORE,
   AGENT_TOOL_REGISTRY,
   AgentRegistry,
@@ -1031,6 +1094,8 @@ export {
   publishAgentToolCall,
   runAgentLoop,
   seedModelPrices,
+  traceLlmTurn,
+  traceToolExecution,
   withToolTimeout
 };
 //# sourceMappingURL=index.js.map