nest-profiler-ai
Types and API of the AI SDK collector.
AiCollectorModuleOptions
Prop
Type
AiCaptureLevel
type AiCaptureLevel = 'none' | 'metadata' | 'redacted' | 'full';How much of one kind of content reaches a stored profile. none keeps the figures and records
nothing of what was said, metadata keeps the shape ([text omitted · 1842 chars]), redacted
is the default and masks credentials and personal data, and full stores it verbatim with no
masking.
AiCaptureFieldLevels
A level per content field, for the setups where one field is more sensitive than the rest.
Resolution runs from the narrowest: a field, then the group it belongs to (prompt covers
instructions and messages, tools covers the three tool fields), then default.
runtimeContext is outside that chain — the AI SDK's runtimeContext on a call and each tool's
toolContext hold the application's own state rather than what was said, so they are recorded
only when the field is named, not even by capture: 'full'. providerPayload, the raw bodies exchanged with the provider, is outside it for the same reason.
Prop
Type
AiCaptureOptions
type AiCaptureOptions = AiCaptureLevel | AiCaptureFieldLevels;AI_CAPTURE_FIELDS / AI_CAPTURE_GROUPS
const AI_CAPTURE_FIELDS: readonly AiCaptureField[];
const AI_CAPTURE_GROUPS: { prompt: [...]; tools: [...] };Every field a level can be set on, and the shorthands that cover several of them at once.
AiRedactionOptions
What the redacted level masks, on top of the built-in detectors it shares with the rest of the
profiler.
Prop
Type
AiSanitizer
type AiSanitizer = (text: string, context: AiRedactionContext) => string;A scrubber of the host's own, run over every text that is kept, after the built-in masking.
AiRedactionContext
What is being masked, handed to sanitize: the content field (or 'error' for a provider
message), the role of the message it belongs to, and the tool it belongs to.
Prop
Type
AI_PII_PATTERNS
const AI_PII_PATTERNS: readonly RegExp[];The personal-data shapes the redacted level masks beyond the credential detectors: email
addresses, international phone numbers, IBANs and US social-security numbers. Exported so a host
can see exactly what is matched, and extend it through redaction.patterns.
AiCallEntry
One provider round-trip. A tool loop records several, distinguished by step.
Prop
Type
AiProviderPayload
The call as the provider saw it, recorded only where capture.providerPayload asks for it.
Prop
Type
AiToolExecutionEntry
One tool the SDK ran between two model calls — real time, spent outside the model.
Prop
Type
instrumentAgentClass
function instrumentAgentClass(agentClass: unknown): boolean;Teaches every AI SDK agent in the process to name itself in the profiles it produces, by wrapping
generate and stream on the agent class's prototype. AiCollectorModule calls it at startup
with the SDK's ToolLoopAgent, so an application never has to — it is exported for a host that
drives the collector itself.
This is what keeps agent attribution free of any call-site change: the application declares its
agent's identity the way the SDK already asks it to, with the id setting, and never imports the
profiler to get it recorded. The wrapper only reads id and opens an async frame around the
original call; it changes no argument, no result and no error, and agents built before it ran are
covered too since a method is looked up on the prototype at call time.
Returns whether this call instrumented the class — false if it was already done, or if the
installed ai exposes no such class.
profileAgent
function profileAgent<A extends AiAgentLike>(agent: A, options?: ProfileAgentOptions): A;The escape hatch, for the two cases instrumentAgentClass cannot reach: an agent that implements
the SDK's Agent interface itself rather than extending ToolLoopAgent, and an agent whose panel
name should differ from its id. A ToolLoopAgent with an id needs none of this.
const support = profileAgent(myCustomAgent, { id: 'support', name: 'Support agent' });
await support.generate({ prompt });
await pipeAgentUIStreamToResponse({ agent: support, uiMessages, response });The returned agent is the same object to every caller, so it can be provided in place of the
original and handed to createAgentUIStream, createAgentUIStreamResponse or
pipeAgentUIStreamToResponse unchanged. When both apply, the wrapper's name wins over the id the
class instrumentation would have used.
Unlike the id route, this puts an import of this package in application code. With the dev-dependency install that file must stay out of production code; to keep the call there, install the profiler as a regular dependency behind the runtime gate.
AiAgentInfo
Which agent drove a generation, as recorded on every entry it produced.
Prop
Type
ProfileAgentOptions
Prop
Type
AiAgentLike
What profileAgent needs of an agent — the AI SDK's Agent, and anything shaped like it.
Prop
Type
AiToolDefinition
A tool as it was declared to the model, with the schema the model had to fill.
Prop
Type
AiToolOrigin
type AiToolOrigin = 'local' | 'mcp' | 'provider' | 'harness';Where a tool comes from, which decides who runs it: local is declared in the application's code,
mcp was discovered on an MCP server at runtime, and provider is built into the model itself (a
provider-run web search, say) and never executes in the application at all.
harness is built into the coding-agent runtime a HarnessAgent drives (Claude Code's Bash or Read) and runs in its sandbox rather than in the application.
AiMessage
One message of the conversation as it was sent to the model.
Prop
Type
AiMessagePart
A message part that is not plain text — a tool call, a tool result, an attachment. An attachment is recorded as its media type and its size or URL, never as its bytes.
Prop
Type
AiApproval
A human-in-the-loop decision on one tool call.
Prop
Type
AiCallSettings
The sampling settings a call was made with — what a reproduction would need.
Prop
Type
AiTokenUsage
Prop
Type
AiCollectorData
What the collector exposes to its panel.
Prop
Type
AiModelPricing
What one model charges. Rates are per per tokens — a million by default, the unit providers
publish. A rate left out falls back to the one it refines, so a model with no cache discount and
no separate thinking rate needs only input and output.
Prop
Type
AiPricingTable
type AiPricingTable = Record<string, AiModelPricing>;Prices by model. A key is provider:model (openai:gpt-4o-mini) or the bare model id
(gpt-4o-mini), matched in that order and case-insensitively. A provider arrives qualified by its
transport (openai.responses), and its root is tried too.
AiPricingSource
type AiPricingSource = () => AiPricingTable | Promise<AiPricingTable>;Loads a price table from wherever the prices live. Called when the module starts and, once
pricingTtl has passed, again in the background — never on the path of a model call.
estimateCost
function estimateCost(
usage: AiTokenUsage | undefined,
provider: string,
model: string,
): number | undefined;What a call cost, from its token counts and the configured prices — undefined when the model has
no price. Cached and thinking tokens are billed at their own rate and are already counted in the
input and output totals, so each is taken out before its rate is applied. The collector applies
this itself; call it directly only to cost something of your own.
mcpToolNamesOf
function mcpToolNamesOf(tools: unknown): Set<string>;The names of the MCP tools in a tool set, told apart from local ones by the marks @ai-sdk/mcp's
client leaves on every tool it builds. The collector calls it on each operation's start event — the
last point at which a tool still says where it came from, since the provider only ever sees names
and schemas — so tools discovered through that client are labelled mcp with nothing declared.
markMcpTools
function markMcpTools(names: readonly string[]): void;Declares tool names as coming from an MCP server. Only needed for an integration that builds its
MCP tools itself rather than through @ai-sdk/mcp's client, which mcpToolNamesOf recognises on
its own. Call it once after loading a server's tools.
Unlike the automatic path, this puts an import of this package in application code. With the dev-dependency install that file must stay out of production code; to keep the call there, install the profiler as a regular dependency behind the runtime gate.
AI_ENTRYPOINT_TYPE
const AI_ENTRYPOINT_TYPE = 'ai';The Profile.entrypoint.type a profiled HTTP request is promoted to once it has called a model.
AiInstrumentation
interface AiInstrumentation {
install(integration: Telemetry): void | Promise<void>;
}An optional integration for an agent implementation the AI SDK core does not ship, listed in AiCollectorModule.forRoot({ instrumentations }). Implementations are NestJS providers. install runs once at startup, after the collector has registered its telemetry integration; one that fails is logged and never takes the application down.
Subpath /pricing
Ready-made pricingSource loaders for public price lists, kept off the main entry for applications that hardcode their prices or load them from their own store.
import { fetchLiteLLMPricing } from '@eleven-labs/nest-profiler-ai/pricing';
AiCollectorModule.forRoot({ pricingSource: () => fetchLiteLLMPricing() });fetchOpenRouterPricing
function fetchOpenRouterPricing(options?: OpenRouterPricingOptions): Promise<AiPricingTable>;Reads the prices of every model OpenRouter serves, ready to hand to pricingSource. The list is
public, so no key is needed. Model ids come back as OpenRouter writes them (openai/gpt-4o-mini),
which is what the AI SDK reports for a call that went through OpenRouter.
Prop
Type
fetchLiteLLMPricing
function fetchLiteLLMPricing(options?: LiteLLMPricingOptions): Promise<AiPricingTable>;Reads the prices LiteLLM keeps for every model of every provider, ready to hand to pricingSource. The file is public, so no key is needed. Model ids come back the way a provider's own API names them (claude-haiku-4-5, gpt-4o-mini), with the prompt-cache rates — the list to pick for direct provider calls and for a HarnessAgent driving Claude Code or Codex, which report tokens but no cost.
Prop
Type
Subpath /harness
Everything specific to @ai-sdk/harness lives here, so the package's main entry never imports it. @ai-sdk/harness is an optional peer dependency, needed only when this subpath is used.
HarnessInstrumentation
import { HarnessInstrumentation } from '@eleven-labs/nest-profiler-ai/harness';
AiCollectorModule.forRoot({ instrumentations: [HarnessInstrumentation] });Profiles the turns of every HarnessAgent in the process — Claude Code, Codex or any other coding-agent runtime driven through the AI SDK. It imports @ai-sdk/harness/agent when installed and hands the class to instrumentHarnessAgentClass.
instrumentHarnessAgentClass
function instrumentHarnessAgentClass(agentClass: unknown, integration: Telemetry): boolean;The HarnessAgent counterpart of instrumentAgentClass. It wraps generate, stream, continueGenerate and continueStream on the class's prototype so each turn is named after the agent's id, and completes the agent's telemetry setting with integration on its first turn — a HarnessAgent reports to no integration otherwise, not even the global ones. HarnessInstrumentation calls it, so an application never has to.
Returns whether this call instrumented the class — false if it was already done, or if what was passed is not a class.
HARNESS_OPERATION
const HARNESS_OPERATION = 'ai.harness';The operation a call recorded from a HarnessAgent turn carries, where generateText records ai.generateText.
Public exports
import { AiCollectorModule } from '@eleven-labs/nest-profiler-ai';
import { AiCollector } from '@eleven-labs/nest-profiler-ai';
import { markMcpTools, isMcpTool, mcpToolNamesOf } from '@eleven-labs/nest-profiler-ai';
import { profileAgent, instrumentAgentClass } from '@eleven-labs/nest-profiler-ai';
import {
configureAiPricing,
loadAiPricing,
resetAiPricing,
pricingFor,
estimateCost,
} from '@eleven-labs/nest-profiler-ai';
import {
AI_COLLECTOR_OPTIONS,
AI_ENTRIES_KEY,
AI_ENTRYPOINT_TYPE,
buildAiEntrypointType,
isAiCall,
} from '@eleven-labs/nest-profiler-ai';
import {
AI_CAPTURE_FIELDS,
AI_CAPTURE_GROUPS,
AI_PII_PATTERNS,
} from '@eleven-labs/nest-profiler-ai';
import type {
AiCollectorModuleOptions,
AiCollectorModuleAsyncOptions,
AiInstrumentation,
AiAgentInfo,
AiAgentLike,
ProfileAgentOptions,
AiEntry,
AiCallEntry,
AiToolExecutionEntry,
AiCollectorData,
AiToolDefinition,
AiToolCall,
AiToolOrigin,
AiApproval,
AiMessage,
AiMessagePart,
AiMessageRole,
AiCallSettings,
AiTokenUsage,
AiProviderPayload,
AiCaptureLevel,
AiCaptureField,
AiCaptureFieldLevels,
AiCaptureGroup,
AiCaptureOptions,
AiCaptureOrigin,
AiRedactionContext,
AiRedactionOptions,
AiSanitizer,
AiModelPricing,
AiPricingTable,
AiPricingSource,
AiPricingConfig,
} from '@eleven-labs/nest-profiler-ai';
// Price lists — their own subpath:
import { fetchOpenRouterPricing, fetchLiteLLMPricing } from '@eleven-labs/nest-profiler-ai/pricing';
import type {
OpenRouterPricingOptions,
LiteLLMPricingOptions,
} from '@eleven-labs/nest-profiler-ai/pricing';
// Harness agents — their own subpath:
import {
HarnessInstrumentation,
instrumentHarnessAgentClass,
HARNESS_OPERATION,
} from '@eleven-labs/nest-profiler-ai/harness';Drive the options from ConfigService (or any provider) with forRootAsync(), added to the dev-only bundle's imports in place of forRoot(). It resolves option values only — for the enabled flag and when to prefer forRoot, see Enabling and disabling the profiler.