@mastra/core 0.16.3 → 0.16.4-alpha.0

package/dist/ai-tracing/span_processors/sensitive-data-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sensitive-data-filter.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/span_processors/sensitive-data-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE3D,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,SAAS,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAE3B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,IAAI,SAA2B;IAC/B,OAAO,CAAC,eAAe,CAAW;IAClC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAiB;gBAE3B,OAAO,GAAE,0BAA+B;IAyBpD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,SAAS;IASnC;;;OAGG;IACH,OAAO,CAAC,UAAU;IAgClB,OAAO,CAAC,SAAS;IAQjB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAIpB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAab,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAGhC"}

package/dist/ai-tracing/spans/base.d.ts

@@ -0,0 +1,59 @@
+import type { AISpan, AISpanType, AISpanTypeMap, AnyAISpan, ChildSpanOptions, ChildEventOptions, EndSpanOptions, ErrorSpanOptions, UpdateSpanOptions, CreateSpanOptions, AITracing, ExportedAISpan } from '../types.js';
+export declare abstract class BaseAISpan<TType extends AISpanType = any> implements AISpan<TType> {
+    abstract id: string;
+    abstract traceId: string;
+    name: string;
+    type: TType;
+    attributes: AISpanTypeMap[TType];
+    parent?: AnyAISpan;
+    startTime: Date;
+    endTime?: Date;
+    isEvent: boolean;
+    isInternal: boolean;
+    aiTracing: AITracing;
+    input?: any;
+    output?: any;
+    errorInfo?: {
+        message: string;
+        id?: string;
+        domain?: string;
+        category?: string;
+        details?: Record<string, any>;
+    };
+    metadata?: Record<string, any>;
+    constructor(options: CreateSpanOptions<TType>, aiTracing: AITracing);
+    /** End the span */
+    abstract end(options?: EndSpanOptions<TType>): void;
+    /** Record an error for the span, optionally end the span as well */
+    abstract error(options: ErrorSpanOptions<TType>): void;
+    /** Update span attributes */
+    abstract update(options: UpdateSpanOptions<TType>): void;
+    createChildSpan<TChildType extends AISpanType>(options: ChildSpanOptions<TChildType>): AISpan<TChildType>;
+    createEventSpan<TChildType extends AISpanType>(options: ChildEventOptions<TChildType>): AISpan<TChildType>;
+    /** Returns `TRUE` if the span is the root span of a trace */
+    get isRootSpan(): boolean;
+    /** Returns `TRUE` if the span is a valid span (not a NO-OP Span) */
+    abstract get isValid(): boolean;
+    /** Get the closest parent spanId that isn't an internal span */
+    getParentSpanId(includeInternalSpans?: boolean): string | undefined;
+    /** Returns a lightweight span ready for export */
+    exportSpan(includeInternalSpans?: boolean): ExportedAISpan<TType>;
+}
+export interface DeepCleanOptions {
+    keysToStrip?: Set<string>;
+    maxDepth?: number;
+}
+/**
+ * Recursively cleans a value by removing circular references and stripping problematic or sensitive keys.
+ * Circular references are replaced with "[Circular]". Unserializable values are replaced with error messages.
+ * Keys like "logger" and "tracingContext" are stripped by default.
+ * A maximum recursion depth is enforced to avoid stack overflow or excessive memory usage.
+ *
+ * @param value - The value to clean (object, array, primitive, etc.)
+ * @param options - Optional configuration:
+ *   - keysToStrip: Set of keys to remove from objects (default: logger, tracingContext)
+ *   - maxDepth: Maximum recursion depth before values are replaced with "[MaxDepth]" (default: 10)
+ * @returns A cleaned version of the input with circular references, specified keys, and overly deep values handled
+ */
+export declare function deepClean(value: any, options?: DeepCleanOptions, _seen?: WeakSet<any>, _depth?: number): any;
+//# sourceMappingURL=base.d.ts.map

package/dist/ai-tracing/spans/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/spans/base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,cAAc,EACf,MAAM,UAAU,CAAC;AAElB,8BAAsB,UAAU,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,CAAE,YAAW,MAAM,CAAC,KAAK,CAAC;IACvF,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,OAAO,EAAE,MAAM,CAAC;IAEzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,IAAI,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,SAAS,CAAC,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC/B,CAAC;IACK,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;gBAE1B,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS;IAqBnE,mBAAmB;IACnB,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,IAAI;IAEnD,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI;IAEtD,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAExD,eAAe,CAAC,UAAU,SAAS,UAAU,EAAE,OAAO,EAAE,gBAAgB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC;IAIzG,eAAe,CAAC,UAAU,SAAS,UAAU,EAAE,OAAO,EAAE,iBAAiB,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC;IAI1G,6DAA6D;IAC7D,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,oEAAoE;IACpE,QAAQ,KAAK,OAAO,IAAI,OAAO,CAAC;IAEhC,gEAAgE;IACzD,eAAe,CAAC,oBAAoB,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;IAQ1E,kDAAkD;IAC3C,UAAU,CAAC,oBAAoB,CAAC,EAAE,OAAO,GAAG,cAAc,CAAC,KAAK,CAAC;CAkBzE;AASD,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,GAAG,EACV,OAAO,GAAE,gBAAqB,EAC9B,KAAK,GAAE,OAAO,CAAC,GAAG,CAAiB,EACnC,MAAM,GAAE,MAAU,GACjB,GAAG,CAwCL"}

package/dist/ai-tracing/spans/default.d.ts

@@ -0,0 +1,13 @@
+import type { AISpanType, AITracing, EndSpanOptions, ErrorSpanOptions, UpdateSpanOptions, CreateSpanOptions } from '../types.js';
+import { BaseAISpan } from './base.js';
+export declare class DefaultAISpan<TType extends AISpanType> extends BaseAISpan<TType> {
+    id: string;
+    traceId: string;
+    constructor(options: CreateSpanOptions<TType>, aiTracing: AITracing);
+    end(options?: EndSpanOptions<TType>): void;
+    error(options: ErrorSpanOptions<TType>): void;
+    update(options: UpdateSpanOptions<TType>): void;
+    get isValid(): boolean;
+    export(): Promise<string>;
+}
+//# sourceMappingURL=default.d.ts.map

package/dist/ai-tracing/spans/default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/spans/default.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAa,MAAM,QAAQ,CAAC;AAE/C,qBAAa,aAAa,CAAC,KAAK,SAAS,UAAU,CAAE,SAAQ,UAAU,CAAC,KAAK,CAAC;IACrE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS;IAcnE,GAAG,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,IAAI;IAiB1C,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI;IAoC7C,MAAM,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAoB/C,IAAI,OAAO,IAAI,OAAO,CAErB;IAEK,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;CAUhC"}

package/dist/ai-tracing/spans/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mastra AI Spans
+ */
+export * from './base.js';
+export * from './default.js';
+export * from './no-op.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-tracing/spans/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/spans/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/ai-tracing/spans/no-op.d.ts

@@ -0,0 +1,15 @@
+/**
+ * No Op Implementation for MastraAITracing
+ */
+import type { AITracing, AISpanType, CreateSpanOptions, EndSpanOptions, UpdateSpanOptions, ErrorSpanOptions } from '../types.js';
+import { BaseAISpan } from './base.js';
+export declare class NoOpAISpan<TType extends AISpanType = any> extends BaseAISpan<TType> {
+    id: string;
+    traceId: string;
+    constructor(options: CreateSpanOptions<TType>, aiTracing: AITracing);
+    end(_options?: EndSpanOptions<TType>): void;
+    error(_options: ErrorSpanOptions<TType>): void;
+    update(_options: UpdateSpanOptions<TType>): void;
+    get isValid(): boolean;
+}
+//# sourceMappingURL=no-op.d.ts.map

package/dist/ai-tracing/spans/no-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"no-op.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/spans/no-op.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC,qBAAa,UAAU,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,CAAE,SAAQ,UAAU,CAAC,KAAK,CAAC;IACxE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS;IAMnE,GAAG,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG,IAAI;IAE3C,KAAK,CAAC,QAAQ,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI;IAE9C,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,IAAI;IAEhD,IAAI,OAAO,IAAI,OAAO,CAErB;CACF"}

package/dist/ai-tracing/{base.d.ts → tracers/base.d.ts}

@@ -1,17 +1,15 @@
 /**
  * MastraAITracing - Abstract base class for AI Tracing implementations
  */
-import { MastraBase } from '../base.js';
-import type { IMastraLogger } from '../logger/index.js';
-import type { RuntimeContext } from '../runtime-context/index.js';
-import type { AITracingInstanceConfig, AISpan, AISpanOptions, AISpanType, AITracingExporter, AISpanProcessor, AITracingEvent, TraceContext, AISpanTypeMap, AnyAISpan } from './types.js';
+import { MastraBase } from '../../base.js';
+import type { IMastraLogger } from '../../logger/index.js';
+import type { TracingConfig, AISpan, AISpanType, AITracingExporter, AISpanProcessor, AITracingEvent, AnyAISpan, StartSpanOptions, CreateSpanOptions, AITracing, CustomSamplerOptions, AnyExportedAISpan } from '../types.js';
 /**
  * Abstract base class for all AI Tracing implementations in Mastra.
- *
  */
-export declare abstract class MastraAITracing extends MastraBase {
-    protected config: Required<AITracingInstanceConfig>;
-    constructor(config: AITracingInstanceConfig);
+export declare abstract class BaseAITracing extends MastraBase implements AITracing {
+    protected config: Required<TracingConfig>;
+    constructor(config: TracingConfig);
     /**
      * Override setLogger to add AI tracing specific initialization log
      */
@@ -21,19 +19,7 @@ export declare abstract class MastraAITracing extends MastraBase {
     /**
      * Start a new span of a specific AISpanType
      */
-    startSpan<TType extends AISpanType>(options: {
-        type: TType;
-        name: string;
-        input?: any;
-        output?: any;
-        attributes?: AISpanTypeMap[TType];
-        metadata?: Record<string, any>;
-        parent?: AnyAISpan;
-        startOptions?: {
-            runtimeContext?: RuntimeContext;
-        };
-        isEvent?: boolean;
-    }): AISpan<TType>;
+    startSpan<TType extends AISpanType>(options: StartSpanOptions<TType>): AISpan<TType>;
     /**
      * Create a new span (called after sampling)
      *
@@ -46,11 +32,11 @@ export declare abstract class MastraAITracing extends MastraBase {
      * - Wire span lifecycle callbacks
      * - Emit span_started event
      */
-    protected abstract createSpan<TType extends AISpanType>(options: AISpanOptions<TType>): AISpan<TType>;
+    protected abstract createSpan<TType extends AISpanType>(options: CreateSpanOptions<TType>): AISpan<TType>;
     /**
      * Get current configuration
      */
-    getConfig(): Readonly<Required<AITracingInstanceConfig>>;
+    getConfig(): Readonly<Required<TracingConfig>>;
     /**
      * Get all exporters
      */
@@ -71,11 +57,12 @@ export declare abstract class MastraAITracing extends MastraBase {
     /**
      * Check if an AI trace should be sampled
      */
-    protected shouldSample(traceContext: TraceContext): boolean;
+    protected shouldSample(options?: CustomSamplerOptions): boolean;
     /**
      * Process a span through all processors
      */
     private processSpan;
+    getSpanForExport(span: AnyAISpan): AnyExportedAISpan | undefined;
     /**
      * Emit a span started event
      */

package/dist/ai-tracing/tracers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/tracers/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,KAAK,EACV,aAAa,EACb,MAAM,EACN,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,SAAS,EAGT,gBAAgB,EAChB,iBAAiB,EACjB,SAAS,EACT,oBAAoB,EACpB,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAOlB;;GAEG;AACH,8BAAsB,aAAc,SAAQ,UAAW,YAAW,SAAS;IACzE,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;gBAE9B,MAAM,EAAE,aAAa;IAcjC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,aAAa;IAYjC,SAAS,KAAK,SAAS,IAAI,iBAAiB,EAAE,CAE7C;IAED,SAAS,KAAK,UAAU,IAAI,eAAe,EAAE,CAE5C;IAMD;;OAEG;IACH,SAAS,CAAC,KAAK,SAAS,UAAU,EAAE,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;IA0BpF;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,SAAS,UAAU,EAAE,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;IAMzG;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAQ9C;;OAEG;IACH,YAAY,IAAI,SAAS,iBAAiB,EAAE;IAI5C;;OAEG;IACH,aAAa,IAAI,SAAS,eAAe,EAAE;IAI3C;;OAEG;IACH,SAAS;IAQT;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAkCzB;;OAEG;IACH,SAAS,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO;IAwB/D;;OAEG;IACH,OAAO,CAAC,WAAW;IAqBnB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,iBAAiB,GAAG,SAAS;IAQhE;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAShD;;OAEG;IACH,SAAS,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAS9C;;OAEG;IACH,SAAS,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAShD;;OAEG;cACa,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBjE;;OAEG;IACH,IAAI,IAAI,IAAI;IASZ;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAUhC"}

package/dist/ai-tracing/tracers/default.d.ts

@@ -0,0 +1,7 @@
+import type { AISpanType, AISpan, TracingConfig, CreateSpanOptions } from '../types.js';
+import { BaseAITracing } from './base.js';
+export declare class DefaultAITracing extends BaseAITracing {
+    constructor(config: TracingConfig);
+    protected createSpan<TType extends AISpanType>(options: CreateSpanOptions<TType>): AISpan<TType>;
+}
+//# sourceMappingURL=default.d.ts.map

package/dist/ai-tracing/tracers/default.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/tracers/default.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEvC,qBAAa,gBAAiB,SAAQ,aAAa;gBACrC,MAAM,EAAE,aAAa;IAIjC,SAAS,CAAC,UAAU,CAAC,KAAK,SAAS,UAAU,EAAE,OAAO,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC;CAIjG"}

package/dist/ai-tracing/tracers/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mastra AI Tracers
+ */
+export * from './base.js';
+export * from './default.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/ai-tracing/tracers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ai-tracing/tracers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,QAAQ,CAAC;AACvB,cAAc,WAAW,CAAC"}

package/dist/ai-tracing/types.d.ts

@@ -2,9 +2,9 @@
  * AI Tracing interfaces
  */
 import type { MastraError } from '../error/index.js';
+import type { IMastraLogger } from '../logger/index.js';
 import type { RuntimeContext } from '../runtime-context/index.js';
 import type { WorkflowRunStatus, WorkflowStepStatus } from '../workflows/index.js';
-import type { MastraAITracing } from './base.js';
 /**
  * AI-specific span types with their associated metadata
  */
@@ -234,11 +234,13 @@ export interface AISpanTypeMap {
  */
 export type AnyAISpanAttributes = AISpanTypeMap[keyof AISpanTypeMap];
 /**
- * AI Span interface with type safety
+ * Base Span interface
  */
-export interface AISpan<TType extends AISpanType> {
+interface BaseSpan<TType extends AISpanType> {
     /** Unique span identifier */
     id: string;
+    /** OpenTelemetry-compatible trace ID (32 hex chars) - present on all spans */
+    traceId: string;
     /** Name of the span */
     name: string;
     /** Type of the span */
@@ -247,16 +249,10 @@ export interface AISpan<TType extends AISpanType> {
     startTime: Date;
     /** When span ended */
     endTime?: Date;
-    /** Is an event span? (event occurs at startTime, has no endTime) */
-    isEvent: boolean;
-    /** AI-specific attributes - strongly typed based on span type */
+    /** Is an internal span? (spans internal to the operation of mastra) */
     attributes?: AISpanTypeMap[TType];
-    /** Parent span reference (undefined for root spans) */
-    parent?: AnyAISpan;
-    /** OpenTelemetry-compatible trace ID (32 hex chars) - present on all spans */
-    traceId: string;
-    /** Pointer to the AITracing instance */
-    aiTracing: MastraAITracing;
+    /** User-defined metadata */
+    metadata?: Record<string, any>;
     /** Input passed at the start of the span */
     input?: any;
     /** Output generated at the end of the span */
@@ -269,75 +265,158 @@ export interface AISpan<TType extends AISpanType> {
         category?: string;
         details?: Record<string, any>;
     };
-    /** User-defined metadata */
-    metadata?: Record<string, any>;
+    /** Is an event span? (event occurs at startTime, has no endTime) */
+    isEvent: boolean;
+}
+/**
+ * AI Span interface, used internally for tracing
+ */
+export interface AISpan<TType extends AISpanType> extends BaseSpan<TType> {
+    /** Is an internal span? (spans internal to the operation of mastra) */
+    isInternal: boolean;
+    /** Parent span reference (undefined for root spans) */
+    parent?: AnyAISpan;
+    /** Pointer to the AITracing instance */
+    aiTracing: AITracing;
     /** End the span */
-    end(options?: {
-        output?: any;
-        attributes?: Partial<AISpanTypeMap[TType]>;
-        metadata?: Record<string, any>;
-    }): void;
+    end(options?: EndSpanOptions<TType>): void;
     /** Record an error for the span, optionally end the span as well */
-    error(options: {
-        error: MastraError | Error;
-        attributes?: Partial<AISpanTypeMap[TType]>;
-        metadata?: Record<string, any>;
-        endSpan?: boolean;
-    }): void;
+    error(options: ErrorSpanOptions<TType>): void;
     /** Update span attributes */
-    update(options?: {
-        input?: any;
-        output?: any;
-        attributes?: Partial<AISpanTypeMap[TType]>;
-        metadata?: Record<string, any>;
-    }): void;
+    update(options: UpdateSpanOptions<TType>): void;
     /** Create child span - can be any span type independent of parent */
-    createChildSpan<TChildType extends AISpanType>(options: {
-        type: TChildType;
-        name: string;
-        input?: any;
-        attributes?: AISpanTypeMap[TChildType];
-        metadata?: Record<string, any>;
-    }): AISpan<TChildType>;
-    /** Create event span - can be any span type independent of parent
-        Event spans have no input, and no endTime.
-    */
-    createEventSpan<TChildType extends AISpanType>(options: {
-        type: TChildType;
-        name: string;
-        output?: any;
-        attributes?: AISpanTypeMap[TChildType];
-        metadata?: Record<string, any>;
-    }): AISpan<TChildType>;
+    createChildSpan<TChildType extends AISpanType>(options: ChildSpanOptions<TChildType>): AISpan<TChildType>;
+    /** Create event span - can be any span type independent of parent */
+    createEventSpan<TChildType extends AISpanType>(options: ChildEventOptions<TChildType>): AISpan<TChildType>;
     /** Returns `TRUE` if the span is the root span of a trace */
     get isRootSpan(): boolean;
     /** Returns `TRUE` if the span is a valid span (not a NO-OP Span) */
     get isValid(): boolean;
+    /** Get the closest parent spanId that isn't an internal span */
+    getParentSpanId(includeInternalSpans?: boolean): string | undefined;
+    /** Returns a lightweight span ready for export */
+    exportSpan(includeInternalSpans?: boolean): ExportedAISpan<TType> | undefined;
+}
+/**
+ * Exported AI Span interface, used for tracing exporters
+ */
+export interface ExportedAISpan<TType extends AISpanType> extends BaseSpan<TType> {
+    /** Parent span id reference (undefined for root spans) */
+    parentSpanId?: string;
+    /** `TRUE` if the span is the root span of a trace */
+    isRootSpan: boolean;
 }
 /**
  * Union type for cases that need to handle any span
  */
 export type AnyAISpan = AISpan<keyof AISpanTypeMap>;
 /**
- * Options for span creation
- */
-export interface AISpanOptions<TType extends AISpanType> {
+ * Union type for cases that need to handle any exported span
+ */
+export type AnyExportedAISpan = ExportedAISpan<keyof AISpanTypeMap>;
+/**
+ * Primary interface for AI Tracing
+ */
+export interface AITracing {
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<Required<TracingConfig>>;
+    /**
+     * Get all exporters
+     */
+    getExporters(): readonly AITracingExporter[];
+    /**
+     * Get all processors
+     */
+    getProcessors(): readonly AISpanProcessor[];
+    /**
+     * Get the logger instance (for exporters and other components)
+     */
+    getLogger(): IMastraLogger;
+    /**
+     * Start a new span of a specific AISpanType
+     */
+    startSpan<TType extends AISpanType>(options: StartSpanOptions<TType>): AISpan<TType>;
+    /**
+     * Shutdown AI tracing and clean up resources
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Override setLogger to add AI tracing specific initialization log
+     */
+    __setLogger(logger: IMastraLogger): void;
+}
+interface CreateBaseOptions<TType extends AISpanType> {
+    /** Span attributes */
+    attributes?: AISpanTypeMap[TType];
+    /** Span metadata */
+    metadata?: Record<string, any>;
     /** Span name */
     name: string;
     /** Span type */
     type: TType;
+    /** Is an internal span? */
+    isInternal?: boolean;
+}
+/**
+ * Options for creating new spans
+ */
+export interface CreateSpanOptions<TType extends AISpanType> extends CreateBaseOptions<TType> {
     /** Input data */
     input?: any;
     /** Output data (for event spans) */
     output?: any;
-    /** Span attributes */
-    attributes?: AISpanTypeMap[TType];
-    /** Span metadata */
-    metadata?: Record<string, any>;
     /** Parent span */
     parent?: AnyAISpan;
     /** Is an event span? */
-    isEvent: boolean;
+    isEvent?: boolean;
+}
+/**
+ * Options for starting new spans
+ */
+export interface StartSpanOptions<TType extends AISpanType> extends CreateSpanOptions<TType> {
+    /**
+     * Options passed when using a custom sampler strategy
+     */
+    customSamplerOptions?: CustomSamplerOptions;
+}
+/**
+ * Options for new child spans
+ */
+export interface ChildSpanOptions<TType extends AISpanType> extends CreateBaseOptions<TType> {
+    /** Input data */
+    input?: any;
+}
+/**
+ * Options for new child events
+ * Event spans have no input, and no endTime
+ */
+export interface ChildEventOptions<TType extends AISpanType> extends CreateBaseOptions<TType> {
+    /** Output data */
+    output?: any;
+}
+interface UpdateBaseOptions<TType extends AISpanType> {
+    /** Span attributes */
+    attributes?: Partial<AISpanTypeMap[TType]>;
+    /** Span metadata */
+    metadata?: Record<string, any>;
+}
+export interface EndSpanOptions<TType extends AISpanType> extends UpdateBaseOptions<TType> {
+    /** Output data */
+    output?: any;
+}
+export interface UpdateSpanOptions<TType extends AISpanType> extends UpdateBaseOptions<TType> {
+    /** Input data */
+    input?: any;
+    /** Output data */
+    output?: any;
+}
+export interface ErrorSpanOptions<TType extends AISpanType> extends UpdateBaseOptions<TType> {
+    /** The error associated with the issue */
+    error: MastraError | Error;
+    /** End the span when true */
+    endSpan?: boolean;
 }
 /**
  * Options passed when starting a new agent or workflow execution
@@ -352,6 +431,8 @@ export interface TracingOptions {
 export interface TracingContext {
     /** Current AI span for creating child spans and adding metadata */
     currentSpan?: AnyAISpan;
+    /** Is the processing internal? Should new spans be created as such? */
+    isInternal?: boolean;
 }
 /**
  * Properties returned to the user for working with traces externally.
@@ -360,6 +441,36 @@ export type TracingProperties = {
     /** Trace ID used on the execution (if the execution was traced). */
     traceId?: string;
 };
+/**
+ * Configuration for a single tracing instance
+ */
+export interface TracingConfig {
+    /** Unique identifier for this config in the ai tracing registry */
+    name: string;
+    /** Service name for tracing */
+    serviceName: string;
+    /** Sampling strategy - controls whether tracing is collected (defaults to ALWAYS) */
+    sampling?: SamplingStrategy;
+    /** Custom exporters */
+    exporters?: AITracingExporter[];
+    /** Custom processors */
+    processors?: AISpanProcessor[];
+    /** Set to `true` if you want to see spans internal to the operation of mastra */
+    includeInternalSpans?: boolean;
+}
+/**
+ * Complete AI Tracing registry configuration
+ */
+export interface ObservabilityRegistryConfig {
+    /** Enables default exporters, with sampling: always, and sensitive data filtering */
+    default?: {
+        enabled?: boolean;
+    };
+    /** Map of tracing instance names to their configurations or pre-instantiated instances */
+    configs?: Record<string, Omit<TracingConfig, 'name'> | AITracing>;
+    /** Optional selector function to choose which tracing instance to use */
+    configSelector?: ConfigSelector;
+}
 /**
  * Sampling strategy types
  */
@@ -369,13 +480,6 @@ export declare enum SamplingStrategyType {
     RATIO = "ratio",
     CUSTOM = "custom"
 }
-/**
- * Context for TraceSampling
- */
-export interface TraceContext {
-    runtimeContext?: RuntimeContext;
-    metadata?: Record<string, any>;
-}
 /**
  * Sampling strategy configuration
  */
@@ -388,36 +492,14 @@ export type SamplingStrategy = {
     probability: number;
 } | {
     type: SamplingStrategyType.CUSTOM;
-    sampler: (traceContext: TraceContext) => boolean;
+    sampler: (options?: CustomSamplerOptions) => boolean;
 };
-export type TracingStrategy = 'realtime' | 'batch-with-updates' | 'insert-only';
-/**
- * Configuration for a single AI tracing instance
- */
-export interface AITracingInstanceConfig {
-    /** Unique identifier for this config in the ai tracing registry */
-    name: string;
-    /** Service name for tracing */
-    serviceName: string;
-    /** Sampling strategy - controls whether tracing is collected (defaults to ALWAYS) */
-    sampling?: SamplingStrategy;
-    /** Custom exporters */
-    exporters?: AITracingExporter[];
-    /** Custom processors */
-    processors?: AISpanProcessor[];
-}
 /**
- * Complete AI Tracing configuration
+ * Options passed when using a custom sampler strategy
  */
-export interface AITracingConfig {
-    /** Enables default exporters, with sampling: always, and sensitive data filtering */
-    default?: {
-        enabled?: boolean;
-    };
-    /** Map of tracing instance names to their configurations or pre-instantiated instances */
-    configs?: Record<string, Omit<AITracingInstanceConfig, 'name'> | MastraAITracing>;
-    /** Optional selector function to choose which tracing instance to use */
-    configSelector?: TracingSelector;
+export interface CustomSamplerOptions {
+    runtimeContext?: RuntimeContext;
+    metadata?: Record<string, any>;
 }
 /**
  * AI Tracing event types
@@ -432,13 +514,13 @@ export declare enum AITracingEventType {
  */
 export type AITracingEvent = {
     type: AITracingEventType.SPAN_STARTED;
-    span: AnyAISpan;
+    exportedSpan: AnyExportedAISpan;
 } | {
     type: AITracingEventType.SPAN_UPDATED;
-    span: AnyAISpan;
+    exportedSpan: AnyExportedAISpan;
 } | {
     type: AITracingEventType.SPAN_ENDED;
-    span: AnyAISpan;
+    exportedSpan: AnyExportedAISpan;
 };
 /**
  * Interface for tracing exporters
@@ -460,14 +542,14 @@ export interface AISpanProcessor {
     /** Processor name */
     name: string;
     /** Process span before export */
-    process(span: AnyAISpan): AnyAISpan | null;
+    process(span?: AnyAISpan): AnyAISpan | undefined;
     /** Shutdown processor */
     shutdown(): Promise<void>;
 }
 /**
- * Context provided to tracing selector functions
+ *  Options passed when using a custom tracing config selector
  */
-export interface AITracingSelectorContext {
+export interface ConfigSelectorOptions {
     /** Runtime context */
     runtimeContext?: RuntimeContext;
 }
@@ -475,5 +557,7 @@ export interface AITracingSelectorContext {
  * Function to select which AI tracing instance to use for a given span
  * Returns the name of the tracing instance, or undefined to use default
  */
-export type TracingSelector = (context: AITracingSelectorContext, availableTracers: ReadonlyMap<string, MastraAITracing>) => string | undefined;
+export type ConfigSelector = (options: ConfigSelectorOptions, availableConfigs: ReadonlyMap<string, AITracing>) => string | undefined;
+export type TracingStrategy = 'realtime' | 'batch-with-updates' | 'insert-only';
+export {};
 //# sourceMappingURL=types.d.ts.map