@newrelic/preflight 0.0.1-pre.1 → 1.0.0

package/dist/shared/events/factory.js

@@ -0,0 +1,351 @@
+import { randomUUID } from 'node:crypto';
+import { safeInt } from '../tokens.js';
+import { createLogger } from '../logger.js';
+const factoryLogger = createLogger('events-factory');
+// Mirror safeInt but for float cost fields: NaN / Infinity -> null (§F1).
+function safeFiniteOrNull(v) {
+    if (v == null)
+        return null;
+    return Number.isFinite(v) ? v : null;
+}
+/**
+ * Warn-once for missing entityGuid.
+ *
+ * NR's entity model usually requires both `appName` and `entityGuid` to attach
+ * events to a specific entity surface (APM service, browser app, etc.).
+ * Without an entityGuid, events still ingest but land in a "standalone events"
+ * view rather than attaching to a service.
+ *
+ * §11.8: warn once PER EVENT TYPE rather than once globally. The old boolean
+ * flag would silence all subsequent factory calls after the very first
+ * missing-entityGuid event, regardless of type — an operator who added
+ * entityGuid to AiRequest but not AiAgentTaskSummary would never see the
+ * warning for the summary events. A Set keyed by eventType gives one warning
+ * per type, covering partial-coverage scenarios without flooding stderr.
+ */
+const entityGuidWarnedTypes = new Set();
+function warnIfMissingEntityGuid(eventType, entityGuid) {
+    if (entityGuidWarnedTypes.has(eventType))
+        return;
+    if (entityGuid === null || entityGuid === undefined || entityGuid === '') {
+        entityGuidWarnedTypes.add(eventType);
+        factoryLogger.warn(`${eventType} created without entityGuid — events will not attach to an NR entity. ` +
+            'Pass entityGuid alongside appName for entity-scoped routing.');
+    }
+}
+/**
+ * Reset the warn-once set. Test-only — production code never resets.
+ * Exported behind a `__` prefix so it's clearly internal.
+ */
+export function __resetEntityGuidWarning() {
+    entityGuidWarnedTypes.clear();
+}
+export function createAiRequest(params) {
+    if (!params.model) {
+        throw new Error('AiRequest requires a model');
+    }
+    if (!params.provider) {
+        throw new Error('AiRequest requires a provider');
+    }
+    if (!params.requestMethod) {
+        throw new Error('AiRequest requires a requestMethod');
+    }
+    if (!params.appName) {
+        throw new Error('AiRequest requires an appName');
+    }
+    warnIfMissingEntityGuid('AiRequest', params.entityGuid);
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        provider: params.provider,
+        model: params.model,
+        requestMethod: params.requestMethod,
+        // Sanitize numeric fields so NaN / Infinity / negative values don't reach
+        // the wire (§EV1). safeInt for integer counts; safeFiniteOrNull for floats.
+        maxTokens: params.maxTokens != null ? safeInt(params.maxTokens) : null,
+        temperature: safeFiniteOrNull(params.temperature),
+        topP: safeFiniteOrNull(params.topP),
+        systemPromptLength: params.systemPromptLength != null ? safeInt(params.systemPromptLength) : null,
+        messageCount: safeInt(params.messageCount),
+        toolCount: safeInt(params.toolCount ?? 0),
+        toolNames: params.toolNames ?? [],
+        thinkingEnabled: params.thinkingEnabled ?? false,
+        thinkingBudgetTokens: params.thinkingBudgetTokens != null ? safeInt(params.thinkingBudgetTokens) : null,
+        streamingEnabled: params.streamingEnabled,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiResponse(params) {
+    if (!params.model) {
+        throw new Error('AiResponse requires a model');
+    }
+    if (!params.provider) {
+        throw new Error('AiResponse requires a provider');
+    }
+    if (!params.appName) {
+        throw new Error('AiResponse requires an appName');
+    }
+    warnIfMissingEntityGuid('AiResponse', params.entityGuid);
+    // coerce token fields through safeInt so NaN, Infinity,
+    // negative numbers, and floats from buggy callers don't propagate as
+    // null/Infinity into the serialized event (where JSON.stringify maps them
+    // to "null", which NR Events API silently drops).
+    const inputTokens = safeInt(params.inputTokens);
+    const outputTokens = safeInt(params.outputTokens);
+    const thinkingTokens = safeInt(params.thinkingTokens);
+    const cacheReadTokens = safeInt(params.cacheReadTokens);
+    const cacheCreationTokens = safeInt(params.cacheCreationTokens);
+    // For Google and OpenAI, inputTokens already includes cached content (cache
+    // tokens are a subset, not additive). Adding them again double-counts (§EV2).
+    // Same provider-aware logic as serialize.ts gen_ai.usage.input_tokens (§S1).
+    //
+    // §11.2: For OpenAI, thinkingTokens (reasoning_tokens from
+    // completion_tokens_details) is already a SUBSET of outputTokens
+    // (completion_tokens) — not a separate additive field. The prior code
+    // added it unconditionally, relying on a comment that said "extractors
+    // produce thinkingTokens=0 for OpenAI" — which is false for o1/o3/o4-mini.
+    // Fix: OpenAI totalTokens = inputTokens + outputTokens (no thinking, no cache).
+    // For Google, thinkingTokens (thoughtsTokenCount) IS disjoint from
+    // outputTokens (candidatesTokenCount) per the Gemini API spec, so it is
+    // still added for that provider.
+    const totalTokens = params.provider === 'openai'
+        ? inputTokens + outputTokens
+        : params.provider === 'google'
+            ? inputTokens + outputTokens + thinkingTokens
+            : inputTokens + outputTokens + thinkingTokens + cacheReadTokens + cacheCreationTokens;
+    // durationMs: coerce to a non-negative integer, matching createAiAgentTaskSummary
+    // (§FAC1). safeInt(NaN|Infinity|negative) → 0. Fractional ms is caller error.
+    const durationMs = safeInt(Number.isFinite(params.durationMs) && params.durationMs >= 0 ? params.durationMs : 0);
+    // timeToFirstTokenMs: apply the same non-negative finite guard (§FAC2).
+    // NaN → null; Infinity → null; negative → null.
+    const timeToFirstTokenMs = params.timeToFirstTokenMs != null &&
+        Number.isFinite(params.timeToFirstTokenMs) &&
+        params.timeToFirstTokenMs >= 0
+        ? params.timeToFirstTokenMs
+        : null;
+    const tokensPerSecond = durationMs > 0 && outputTokens > 0 ? (outputTokens / durationMs) * 1000 : null;
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        provider: params.provider,
+        model: params.model,
+        durationMs,
+        timeToFirstTokenMs,
+        tokensPerSecond,
+        inputTokens,
+        outputTokens,
+        thinkingTokens,
+        cacheReadTokens,
+        cacheCreationTokens,
+        totalTokens,
+        costInputUsd: safeFiniteOrNull(params.costInputUsd),
+        costOutputUsd: safeFiniteOrNull(params.costOutputUsd),
+        costThinkingUsd: safeFiniteOrNull(params.costThinkingUsd),
+        costCacheReadUsd: safeFiniteOrNull(params.costCacheReadUsd),
+        costCacheCreationUsd: safeFiniteOrNull(params.costCacheCreationUsd),
+        costTotalUsd: safeFiniteOrNull(params.costTotalUsd),
+        stopReason: params.stopReason ?? null,
+        contentBlockTypes: params.contentBlockTypes ?? [],
+        error: params.error ?? null,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiMessage(params) {
+    if (!params.role) {
+        throw new Error('AiMessage requires a role');
+    }
+    // 13: required-field validation made uniform across the
+    // three factory functions. `content` is typed as `string` but JS callers
+    // bypass the type system; reject `null` / `undefined` here so downstream
+    // serialization doesn't emit `content: "null"` / `content: "undefined"`
+    // verbatim. Empty string is allowed — a deliberately-empty assistant
+    // response is a valid record.
+    if (params.content === null || params.content === undefined) {
+        throw new Error('AiMessage requires content');
+    }
+    if (!params.appName) {
+        throw new Error('AiMessage requires an appName');
+    }
+    warnIfMissingEntityGuid('AiMessage', params.entityGuid);
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        role: params.role,
+        content: params.content,
+        contentLength: safeInt(params.contentLength),
+        sequence: params.sequence,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiAgentTaskSummary(params) {
+    if (!params.traceId) {
+        throw new Error('AiAgentTaskSummary requires a traceId');
+    }
+    if (!params.spanId) {
+        throw new Error('AiAgentTaskSummary requires a spanId');
+    }
+    if (!params.taskName) {
+        throw new Error('AiAgentTaskSummary requires a taskName');
+    }
+    if (!params.appName) {
+        throw new Error('AiAgentTaskSummary requires an appName');
+    }
+    warnIfMissingEntityGuid('AiAgentTaskSummary', params.entityGuid);
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        traceId: params.traceId,
+        spanId: params.spanId,
+        taskName: params.taskName,
+        // Sanitize numeric fields through safeInt so a buggy caller passing NaN /
+        // Infinity doesn't propagate through serialize.ts as `null` and confuse
+        // downstream NRQL aggregations.
+        durationMs: safeInt(params.durationMs),
+        totalLlmCalls: safeInt(params.totalLlmCalls),
+        totalToolCalls: safeInt(params.totalToolCalls),
+        totalTokens: safeInt(params.totalTokens),
+        totalCostUsd: safeFiniteOrNull(params.totalCostUsd),
+        stepCount: safeInt(params.stepCount),
+        success: params.success,
+        provider: params.provider,
+        delegationCount: params.delegationCount !== undefined ? safeInt(params.delegationCount) : undefined,
+        spawnCount: params.spawnCount !== undefined ? safeInt(params.spawnCount) : undefined,
+        delegationDepth: params.delegationDepth !== undefined ? safeInt(params.delegationDepth) : undefined,
+        interAgentMessages: params.interAgentMessages !== undefined ? safeInt(params.interAgentMessages) : undefined,
+        delegationOverheadMs: params.delegationOverheadMs !== undefined ? safeInt(params.delegationOverheadMs) : undefined,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiAntiPattern(params) {
+    if (!params.traceId) {
+        throw new Error('AiAntiPattern requires a traceId');
+    }
+    if (!params.patternType) {
+        throw new Error('AiAntiPattern requires a patternType');
+    }
+    if (!params.severity) {
+        throw new Error('AiAntiPattern requires a severity');
+    }
+    if (!params.description) {
+        throw new Error('AiAntiPattern requires a description');
+    }
+    if (!params.appName) {
+        throw new Error('AiAntiPattern requires an appName');
+    }
+    warnIfMissingEntityGuid('AiAntiPattern', params.entityGuid);
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        traceId: params.traceId,
+        patternType: params.patternType,
+        severity: params.severity,
+        description: params.description,
+        provider: params.provider,
+        toolName: params.toolName,
+        repeatCount: params.repeatCount !== undefined ? safeInt(params.repeatCount) : undefined,
+        depthIndex: params.depthIndex !== undefined ? safeInt(params.depthIndex) : undefined,
+        taskComplexity: params.taskComplexity,
+        contextPressure: safeFiniteOrNull(params.contextPressure),
+        tokenShare: safeFiniteOrNull(params.tokenShare),
+        attemptCount: params.attemptCount !== undefined ? safeInt(params.attemptCount) : undefined,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiAgentMessage(params) {
+    if (!params.traceId) {
+        throw new Error('AiAgentMessage requires a traceId');
+    }
+    if (!params.fromAgent) {
+        throw new Error('AiAgentMessage requires a fromAgent');
+    }
+    if (!params.toAgent) {
+        throw new Error('AiAgentMessage requires a toAgent');
+    }
+    if (!params.messageType) {
+        throw new Error('AiAgentMessage requires a messageType');
+    }
+    if (!params.appName) {
+        throw new Error('AiAgentMessage requires an appName');
+    }
+    warnIfMissingEntityGuid('AiAgentMessage', params.entityGuid);
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        traceId: params.traceId,
+        fromAgent: params.fromAgent,
+        toAgent: params.toAgent,
+        messageType: params.messageType,
+        provider: params.provider,
+        tokenCount: params.tokenCount === undefined ? undefined : safeInt(params.tokenCount),
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+export function createAiContextReset(params) {
+    if (!params.traceId) {
+        throw new Error('AiContextReset requires a traceId');
+    }
+    if (!params.conversationId) {
+        throw new Error('AiContextReset requires a conversationId');
+    }
+    if (!params.reason) {
+        throw new Error('AiContextReset requires a reason');
+    }
+    if (!params.appName) {
+        throw new Error('AiContextReset requires an appName');
+    }
+    warnIfMissingEntityGuid('AiContextReset', params.entityGuid);
+    const tokensBefore = safeInt(params.tokensBefore);
+    const tokensAfter = safeInt(params.tokensAfter);
+    // Derived fields — compute here so callers don't have to remember the
+    // contract. tokensRemoved is `before - after` (clamped at 0 because a
+    // post-reset count higher than the pre-reset count is nonsensical, and
+    // the resulting negative value would corrupt NRQL aggregations).
+    const tokensRemoved = Math.max(0, tokensBefore - tokensAfter);
+    // tokensBefore === 0 → identity reset (no content to compress); return 1.0
+    // so dashboards averaging compressionRatio don't see artificially low values
+    // from no-op resets. ratio > 1.0 is possible (summarizer preamble > savings)
+    // and is preserved; a debug log makes the rare case diagnosable (§F2).
+    let compressionRatio;
+    if (tokensBefore === 0) {
+        compressionRatio = 1;
+    }
+    else {
+        compressionRatio = tokensAfter / tokensBefore;
+        if (compressionRatio > 1) {
+            factoryLogger.debug('AiContextReset compressionRatio > 1 (post-reset tokens exceed pre-reset)', {
+                tokensBefore,
+                tokensAfter,
+                compressionRatio,
+            });
+        }
+    }
+    return {
+        id: params.id ?? randomUUID(),
+        timestamp: params.timestamp ?? Date.now(),
+        traceId: params.traceId,
+        conversationId: params.conversationId,
+        tokensBefore,
+        tokensAfter,
+        tokensRemoved,
+        compressionRatio,
+        reason: params.reason,
+        provider: params.provider,
+        turnsRemoved: params.turnsRemoved !== undefined ? safeInt(params.turnsRemoved) : undefined,
+        'nr.appName': params.appName,
+        'nr.entityGuid': params.entityGuid ?? null,
+        customAttributes: params.customAttributes ?? {},
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/shared/events/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/shared/events/factory.ts"],"names":[],"mappings":"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"}

package/dist/shared/events/index.d.ts

@@ -0,0 +1,6 @@
+export type { AiProvider, AiRequestMethod, AiRequest, AiResponse, AiMessageRole, AiMessage, NrEventData, AiAgentTaskSummary, AntiPatternType, AiAntiPattern, AiAgentMessage, AiContextReset, } from './types.js';
+export { createAiRequest, createAiResponse, createAiMessage, createAiAgentTaskSummary, createAiAntiPattern, createAiAgentMessage, createAiContextReset, } from './factory.js';
+export type { CreateAiRequestParams, CreateAiResponseParams, CreateAiMessageParams, CreateAiAgentTaskSummaryParams, CreateAiAntiPatternParams, CreateAiAgentMessageParams, CreateAiContextResetParams, } from './factory.js';
+export { aiRequestToNrEvent, aiResponseToNrEvent, aiMessageToNrEvent, aiAgentTaskSummaryToNrEvent, aiAntiPatternToNrEvent, aiAgentMessageToNrEvent, aiContextResetToNrEvent, EVENT_SCHEMA_VERSION, } from './serialize.js';
+export type { SerializeOptions } from './serialize.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/events/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,eAAe,EACf,SAAS,EACT,UAAU,EACV,aAAa,EACb,SAAS,EACT,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,8BAA8B,EAC9B,yBAAyB,EACzB,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/shared/events/index.js

@@ -0,0 +1,3 @@
+export { createAiRequest, createAiResponse, createAiMessage, createAiAgentTaskSummary, createAiAntiPattern, createAiAgentMessage, createAiContextReset, } from './factory.js';
+export { aiRequestToNrEvent, aiResponseToNrEvent, aiMessageToNrEvent, aiAgentTaskSummaryToNrEvent, aiAntiPatternToNrEvent, aiAgentMessageToNrEvent, aiContextResetToNrEvent, EVENT_SCHEMA_VERSION, } from './serialize.js';
+//# sourceMappingURL=index.js.map

package/dist/shared/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shared/events/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,cAAc,CAAC;AAUtB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,gBAAgB,CAAC"}

package/dist/shared/events/serialize.d.ts

@@ -0,0 +1,87 @@
+import type { AiRequest, AiResponse, AiMessage, AiAgentTaskSummary, AiAntiPattern, AiAgentMessage, AiContextReset, NrEventData } from './types.js';
+/**
+ * High-security mode field-suppression contract.
+ *
+ * When `highSecurity: true` is passed to a serializer, the resulting
+ * NrEventData has the following content-bearing fields suppressed:
+ *
+ *   - `error.message` is **omitted entirely** (provider error bodies often
+ *     echo verbatim prompt fragments back). `error.type` and
+ *     `error.statusCode` are still emitted — they are bounded enum-like
+ *     values useful for triage and don't leak content. Applies to
+ *     `aiResponseToNrEvent`.
+ *
+ *   - Every string value in `customAttributes` is **clipped to 256
+ *     characters** (with a trailing `...` marker). Numeric custom
+ *     attributes pass through unchanged. Applies to **all** serializers.
+ *     In normal mode (highSecurity: false / omitted), string values are
+ *     still truncated at 4000 chars so a long attribute cannot push the
+ *     event past NR's 4096-byte per-attribute cap.
+ *
+ * Structural / metadata fields are intentionally NOT suppressed in
+ * high-security mode — they are bounded identifiers, not free-form
+ * content:
+ *
+ *   - `toolNames`, `contentBlockTypes`, `requestMethod`, `model`,
+ *     `provider`, `stopReason`, `patternType`, `severity`, etc.
+ *   - `AiAntiPattern.description` (enum-derived diagnostic text written
+ *     by the agent, not by the upstream model).
+ *
+ * Per-message content (`AiMessage.content`) is gated separately by
+ * `recordContent` on the consumer's `AgentConfig`, which `highSecurity`
+ * forces to `false` at config-load time. The message serializer assumes
+ * the caller has already honored that flag and does not clip `content`
+ * here.
+ */
+export interface SerializeOptions {
+    readonly highSecurity?: boolean;
+}
+/**
+ * Event schema version. Bump whenever the wire-format
+ * shape of any serializer changes in a way that downstream NR dashboards
+ * built on the previous shape would silently mis-render. The current value
+ * is stamped on every emitted event (`schemaVersion: 1`) so dashboards can
+ * filter on `WHERE schemaVersion = 1` and catch a future migration before
+ * the data renders incorrectly.
+ *
+ * Bumping policy:
+ *   - Add a field: NO bump required (new field is null/missing on old events).
+ *   - Remove or rename a field: bump.
+ *   - Change a field's type or unit: bump.
+ *   - Change a field's semantic meaning: bump.
+ *
+ * The §4.9 metric-API summary migration is an analogous (separate) wire
+ * change and is covered by NR's metric `type` field, not this schema version.
+ */
+export declare const EVENT_SCHEMA_VERSION = 1;
+export declare function aiRequestToNrEvent(event: AiRequest, options?: SerializeOptions): NrEventData;
+export declare function aiResponseToNrEvent(event: AiResponse, options?: SerializeOptions): NrEventData;
+export declare function aiMessageToNrEvent(event: AiMessage, options?: SerializeOptions): NrEventData;
+/**
+ * dotted-key naming convention for the four newer
+ * agent-shaped event types (`AiAgentTaskSummary`, `AiAntiPattern`,
+ * `AiAgentMessage`, `AiContextReset`). These serializers emit attributes
+ * with a `<namespace>.<field>` shape (e.g. `ai.agent.task_duration_ms`,
+ * `ai.antipattern.severity`) alongside top-level non-namespaced fields
+ * (e.g. `id`, `timestamp`, `taskName`).
+ *
+ * The dotted form is the OTel-style and aligns with `gen_ai.*` already in
+ * use on AiRequest/AiResponse — operators querying these in NRQL must
+ * backtick-quote: `SELECT \`ai.agent.task_duration_ms\` FROM AiAgentTaskSummary`.
+ *
+ * The mixed top-level + namespaced shape (`taskName` flat, `ai.agent.*`
+ * dotted) is intentional: the top-level fields carry record identity that
+ * the eventType bucket already groups by (you query `FROM AiAgentTaskSummary`
+ * so `eventType` provides the namespace), while the `ai.<area>.*` fields
+ * cluster metric-shaped attributes by source area so dashboards can
+ * `SELECT keyset() WHERE attribute LIKE 'ai.agent.%'`.
+ *
+ * This convention is documented here rather than enforced — adding new
+ * fields to these event types should follow it for consistency, but the
+ * library does not validate the shape at runtime.
+ */
+export declare function aiAgentTaskSummaryToNrEvent(event: AiAgentTaskSummary, options?: SerializeOptions): NrEventData;
+export declare function aiAntiPatternToNrEvent(event: AiAntiPattern, options?: SerializeOptions): NrEventData;
+export declare function aiAgentMessageToNrEvent(event: AiAgentMessage, options?: SerializeOptions): NrEventData;
+export declare function aiContextResetToNrEvent(event: AiContextReset, options?: SerializeOptions): NrEventData;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/shared/events/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/shared/events/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,SAAS,EACT,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAsIpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAsED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAwC5F;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,CA8F9F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,WAAW,CAoB5F;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,kBAAkB,EACzB,OAAO,CAAC,EAAE,gBAAgB,GACzB,WAAW,CAkCb;AAED,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,WAAW,CA0Bb;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,gBAAgB,GACzB,WAAW,CAoBb;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,cAAc,EACrB,OAAO,CAAC,EAAE,gBAAgB,GACzB,WAAW,CAuBb"}