mojentic 1.0.0

package/dist/tracer/tracerEvents.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Tracer event types for tracking system interactions.
+ *
+ * Tracer events are used to track system interactions for observability purposes.
+ * They are distinct from regular events which are used for agent communication.
+ */
+import { ToolCall } from '../llm/models';
+/**
+ * Type alias for TracerEvent constructor functions.
+ * Uses abstract new to indicate these are class constructors that can be instantiated.
+ * The never[] parameter list indicates we don't care about the specific constructor arguments
+ * when using this type for filtering/type-checking purposes.
+ */
+export type TracerEventConstructor = abstract new (...args: never[]) => TracerEvent;
+/**
+ * Base class for all tracer-specific events.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMCallTracerEvent(
+ *   'gpt-4',
+ *   [{ role: 'user', content: 'Hello' }],
+ *   0.7,
+ *   undefined,
+ *   'my-correlation-id'
+ * );
+ * console.log(event.printableSummary());
+ * ```
+ */
+export declare abstract class TracerEvent {
+    /**
+     * Timestamp when the event occurred (milliseconds since epoch)
+     */
+    readonly timestamp: number;
+    /**
+     * UUID string that is copied from cause-to-effect for tracing events
+     */
+    readonly correlationId: string;
+    /**
+     * Source of the event (optional, for context)
+     */
+    readonly source?: string;
+    /**
+     * Creates a new tracer event.
+     *
+     * @param timestamp - Timestamp when the event occurred
+     * @param correlationId - UUID for tracing related events
+     * @param source - Optional source identifier
+     */
+    constructor(timestamp: number, correlationId: string, source?: string);
+    /**
+     * Set the timestamp for testing purposes only.
+     * This method allows tests to manipulate timestamps without type casting.
+     *
+     * @param timestamp - The timestamp to set (milliseconds since epoch)
+     * @throws Error if called outside of test environment
+     *
+     * @internal This method is only for testing and should not be used in production code.
+     */
+    setTimestampForTesting(timestamp: number): void;
+    /**
+     * Return a formatted string summary of the event.
+     *
+     * @returns A formatted string with the event information
+     */
+    printableSummary(): string;
+}
+/**
+ * Records when an LLM is called with specific messages.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMCallTracerEvent(
+ *   'gpt-4',
+ *   [Message.user('Hello')],
+ *   0.7,
+ *   [dateTool.descriptor()],
+ *   'corr-123'
+ * );
+ * ```
+ */
+export declare class LLMCallTracerEvent extends TracerEvent {
+    /**
+     * The LLM model that was used
+     */
+    readonly model: string;
+    /**
+     * The messages sent to the LLM
+     */
+    readonly messages: unknown[];
+    /**
+     * The temperature setting used for the call
+     */
+    readonly temperature: number;
+    /**
+     * The tools available to the LLM, if any
+     */
+    readonly tools?: Record<string, unknown>[];
+    constructor(model: string, messages: unknown[], temperature?: number, tools?: Record<string, unknown>[], correlationId?: string, source?: string);
+    printableSummary(): string;
+}
+/**
+ * Records when an LLM responds to a call.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMResponseTracerEvent(
+ *   'gpt-4',
+ *   'Hello! How can I help?',
+ *   undefined,
+ *   150.5,
+ *   'corr-123'
+ * );
+ * ```
+ */
+export declare class LLMResponseTracerEvent extends TracerEvent {
+    /**
+     * The LLM model that was used
+     */
+    readonly model: string;
+    /**
+     * The content of the LLM response
+     */
+    readonly content: string;
+    /**
+     * Any tool calls made by the LLM
+     */
+    readonly toolCalls?: ToolCall[];
+    /**
+     * Duration of the LLM call in milliseconds
+     */
+    readonly callDurationMs?: number;
+    constructor(model: string, content: string, toolCalls?: ToolCall[], callDurationMs?: number, correlationId?: string, source?: string);
+    printableSummary(): string;
+}
+/**
+ * Records when a tool is called during agent execution.
+ *
+ * @example
+ * ```typescript
+ * const event = new ToolCallTracerEvent(
+ *   'resolve_date',
+ *   { date_string: 'tomorrow' },
+ *   { resolved: '2025-11-16' },
+ *   'my-agent',
+ *   25.3,
+ *   'corr-123'
+ * );
+ * ```
+ */
+export declare class ToolCallTracerEvent extends TracerEvent {
+    /**
+     * Name of the tool that was called
+     */
+    readonly toolName: string;
+    /**
+     * Arguments provided to the tool
+     */
+    readonly arguments: Record<string, unknown>;
+    /**
+     * Result returned by the tool
+     */
+    readonly result: unknown;
+    /**
+     * Name of the agent or component that called the tool
+     */
+    readonly caller?: string;
+    /**
+     * Duration of the tool call in milliseconds
+     */
+    readonly callDurationMs?: number;
+    constructor(toolName: string, args: Record<string, unknown>, result: unknown, caller?: string, callDurationMs?: number, correlationId?: string, source?: string);
+    printableSummary(): string;
+}
+/**
+ * Records interactions between agents.
+ *
+ * @example
+ * ```typescript
+ * const event = new AgentInteractionTracerEvent(
+ *   'coordinator',
+ *   'specialist',
+ *   'task_request',
+ *   'event-456',
+ *   'corr-123'
+ * );
+ * ```
+ */
+export declare class AgentInteractionTracerEvent extends TracerEvent {
+    /**
+     * Name of the agent sending the event
+     */
+    readonly fromAgent: string;
+    /**
+     * Name of the agent receiving the event
+     */
+    readonly toAgent: string;
+    /**
+     * Type of event being processed
+     */
+    readonly eventType: string;
+    /**
+     * Unique identifier for the event
+     */
+    readonly eventId?: string;
+    constructor(fromAgent: string, toAgent: string, eventType: string, eventId?: string, correlationId?: string, source?: string);
+    printableSummary(): string;
+}
+//# sourceMappingURL=tracerEvents.d.ts.map

package/dist/tracer/tracerEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracerEvents.d.ts","sourceRoot":"","sources":["../../src/tracer/tracerEvents.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC;AAEpF;;;;;;;;;;;;;;GAcG;AACH,8BAAsB,WAAW;IAC/B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;gBACS,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;IAMrE;;;;;;;;OAQG;IACH,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAa/C;;;;OAIG;IACH,gBAAgB,IAAI,MAAM;CAK3B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,SAAQ,WAAW;IACjD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;gBAGzC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EAAE,EACnB,WAAW,GAAE,MAAY,EACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACjC,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM;IASjB,gBAAgB,IAAI,MAAM;CAsB3B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,WAAW;IACrD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAG/B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,QAAQ,EAAE,EACtB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM;IASjB,gBAAgB,IAAI,MAAM;CAqB3B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;gBAG/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM;IAUjB,gBAAgB,IAAI,MAAM;CAyB3B;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,2BAA4B,SAAQ,WAAW;IAC1D;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAGxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM;IASjB,gBAAgB,IAAI,MAAM;CAW3B"}

package/dist/tracer/tracerEvents.js

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * Tracer event types for tracking system interactions.
+ *
+ * Tracer events are used to track system interactions for observability purposes.
+ * They are distinct from regular events which are used for agent communication.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentInteractionTracerEvent = exports.ToolCallTracerEvent = exports.LLMResponseTracerEvent = exports.LLMCallTracerEvent = exports.TracerEvent = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Base class for all tracer-specific events.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMCallTracerEvent(
+ *   'gpt-4',
+ *   [{ role: 'user', content: 'Hello' }],
+ *   0.7,
+ *   undefined,
+ *   'my-correlation-id'
+ * );
+ * console.log(event.printableSummary());
+ * ```
+ */
+class TracerEvent {
+    /**
+     * Timestamp when the event occurred (milliseconds since epoch)
+     */
+    timestamp;
+    /**
+     * UUID string that is copied from cause-to-effect for tracing events
+     */
+    correlationId;
+    /**
+     * Source of the event (optional, for context)
+     */
+    source;
+    /**
+     * Creates a new tracer event.
+     *
+     * @param timestamp - Timestamp when the event occurred
+     * @param correlationId - UUID for tracing related events
+     * @param source - Optional source identifier
+     */
+    constructor(timestamp, correlationId, source) {
+        this.timestamp = timestamp;
+        this.correlationId = correlationId;
+        this.source = source;
+    }
+    /**
+     * Set the timestamp for testing purposes only.
+     * This method allows tests to manipulate timestamps without type casting.
+     *
+     * @param timestamp - The timestamp to set (milliseconds since epoch)
+     * @throws Error if called outside of test environment
+     *
+     * @internal This method is only for testing and should not be used in production code.
+     */
+    setTimestampForTesting(timestamp) {
+        if (process.env.NODE_ENV !== 'test') {
+            throw new Error('setTimestampForTesting can only be called in test environment');
+        }
+        // Using Object.defineProperty to modify the readonly property
+        Object.defineProperty(this, 'timestamp', {
+            value: timestamp,
+            writable: false,
+            enumerable: true,
+            configurable: true,
+        });
+    }
+    /**
+     * Return a formatted string summary of the event.
+     *
+     * @returns A formatted string with the event information
+     */
+    printableSummary() {
+        const eventTime = new Date(this.timestamp).toTimeString().split(' ')[0];
+        const ms = String(this.timestamp % 1000).padStart(3, '0');
+        return `[${eventTime}.${ms}] ${this.constructor.name} (correlation_id: ${this.correlationId})`;
+    }
+}
+exports.TracerEvent = TracerEvent;
+/**
+ * Records when an LLM is called with specific messages.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMCallTracerEvent(
+ *   'gpt-4',
+ *   [Message.user('Hello')],
+ *   0.7,
+ *   [dateTool.descriptor()],
+ *   'corr-123'
+ * );
+ * ```
+ */
+class LLMCallTracerEvent extends TracerEvent {
+    /**
+     * The LLM model that was used
+     */
+    model;
+    /**
+     * The messages sent to the LLM
+     */
+    messages;
+    /**
+     * The temperature setting used for the call
+     */
+    temperature;
+    /**
+     * The tools available to the LLM, if any
+     */
+    tools;
+    constructor(model, messages, temperature = 1.0, tools, correlationId, source) {
+        super(Date.now(), correlationId || (0, crypto_1.randomUUID)(), source);
+        this.model = model;
+        this.messages = messages;
+        this.temperature = temperature;
+        this.tools = tools;
+    }
+    printableSummary() {
+        const baseSummary = super.printableSummary();
+        let summary = `${baseSummary}\n   Model: ${this.model}`;
+        if (this.messages.length > 0) {
+            const msgCount = this.messages.length;
+            summary += `\n   Messages: ${msgCount} message${msgCount !== 1 ? 's' : ''}`;
+        }
+        if (this.temperature !== 1.0) {
+            summary += `\n   Temperature: ${this.temperature}`;
+        }
+        if (this.tools && this.tools.length > 0) {
+            const toolNames = this.tools
+                .map((t) => t.function?.name || 'unknown')
+                .join(', ');
+            summary += `\n   Available Tools: ${toolNames}`;
+        }
+        return summary;
+    }
+}
+exports.LLMCallTracerEvent = LLMCallTracerEvent;
+/**
+ * Records when an LLM responds to a call.
+ *
+ * @example
+ * ```typescript
+ * const event = new LLMResponseTracerEvent(
+ *   'gpt-4',
+ *   'Hello! How can I help?',
+ *   undefined,
+ *   150.5,
+ *   'corr-123'
+ * );
+ * ```
+ */
+class LLMResponseTracerEvent extends TracerEvent {
+    /**
+     * The LLM model that was used
+     */
+    model;
+    /**
+     * The content of the LLM response
+     */
+    content;
+    /**
+     * Any tool calls made by the LLM
+     */
+    toolCalls;
+    /**
+     * Duration of the LLM call in milliseconds
+     */
+    callDurationMs;
+    constructor(model, content, toolCalls, callDurationMs, correlationId, source) {
+        super(Date.now(), correlationId || (0, crypto_1.randomUUID)(), source);
+        this.model = model;
+        this.content = content;
+        this.toolCalls = toolCalls;
+        this.callDurationMs = callDurationMs;
+    }
+    printableSummary() {
+        const baseSummary = super.printableSummary();
+        let summary = `${baseSummary}\n   Model: ${this.model}`;
+        if (this.content) {
+            const contentPreview = this.content.length > 100 ? this.content.substring(0, 100) + '...' : this.content;
+            summary += `\n   Content: ${contentPreview}`;
+        }
+        if (this.toolCalls && this.toolCalls.length > 0) {
+            const toolCount = this.toolCalls.length;
+            summary += `\n   Tool Calls: ${toolCount} call${toolCount !== 1 ? 's' : ''}`;
+        }
+        if (this.callDurationMs !== undefined) {
+            summary += `\n   Duration: ${this.callDurationMs.toFixed(2)}ms`;
+        }
+        return summary;
+    }
+}
+exports.LLMResponseTracerEvent = LLMResponseTracerEvent;
+/**
+ * Records when a tool is called during agent execution.
+ *
+ * @example
+ * ```typescript
+ * const event = new ToolCallTracerEvent(
+ *   'resolve_date',
+ *   { date_string: 'tomorrow' },
+ *   { resolved: '2025-11-16' },
+ *   'my-agent',
+ *   25.3,
+ *   'corr-123'
+ * );
+ * ```
+ */
+class ToolCallTracerEvent extends TracerEvent {
+    /**
+     * Name of the tool that was called
+     */
+    toolName;
+    /**
+     * Arguments provided to the tool
+     */
+    arguments;
+    /**
+     * Result returned by the tool
+     */
+    result;
+    /**
+     * Name of the agent or component that called the tool
+     */
+    caller;
+    /**
+     * Duration of the tool call in milliseconds
+     */
+    callDurationMs;
+    constructor(toolName, args, result, caller, callDurationMs, correlationId, source) {
+        super(Date.now(), correlationId || (0, crypto_1.randomUUID)(), source);
+        this.toolName = toolName;
+        this.arguments = args;
+        this.result = result;
+        this.caller = caller;
+        this.callDurationMs = callDurationMs;
+    }
+    printableSummary() {
+        const baseSummary = super.printableSummary();
+        let summary = `${baseSummary}\n   Tool: ${this.toolName}`;
+        if (Object.keys(this.arguments).length > 0) {
+            summary += `\n   Arguments: ${JSON.stringify(this.arguments)}`;
+        }
+        if (this.result !== undefined) {
+            const resultStr = JSON.stringify(this.result);
+            const resultPreview = resultStr.length > 100 ? resultStr.substring(0, 100) + '...' : resultStr;
+            summary += `\n   Result: ${resultPreview}`;
+        }
+        if (this.caller) {
+            summary += `\n   Caller: ${this.caller}`;
+        }
+        if (this.callDurationMs !== undefined) {
+            summary += `\n   Duration: ${this.callDurationMs.toFixed(2)}ms`;
+        }
+        return summary;
+    }
+}
+exports.ToolCallTracerEvent = ToolCallTracerEvent;
+/**
+ * Records interactions between agents.
+ *
+ * @example
+ * ```typescript
+ * const event = new AgentInteractionTracerEvent(
+ *   'coordinator',
+ *   'specialist',
+ *   'task_request',
+ *   'event-456',
+ *   'corr-123'
+ * );
+ * ```
+ */
+class AgentInteractionTracerEvent extends TracerEvent {
+    /**
+     * Name of the agent sending the event
+     */
+    fromAgent;
+    /**
+     * Name of the agent receiving the event
+     */
+    toAgent;
+    /**
+     * Type of event being processed
+     */
+    eventType;
+    /**
+     * Unique identifier for the event
+     */
+    eventId;
+    constructor(fromAgent, toAgent, eventType, eventId, correlationId, source) {
+        super(Date.now(), correlationId || (0, crypto_1.randomUUID)(), source);
+        this.fromAgent = fromAgent;
+        this.toAgent = toAgent;
+        this.eventType = eventType;
+        this.eventId = eventId;
+    }
+    printableSummary() {
+        const baseSummary = super.printableSummary();
+        let summary = `${baseSummary}\n   From: ${this.fromAgent} → To: ${this.toAgent}`;
+        summary += `\n   Event Type: ${this.eventType}`;
+        if (this.eventId) {
+            summary += `\n   Event ID: ${this.eventId}`;
+        }
+        return summary;
+    }
+}
+exports.AgentInteractionTracerEvent = AgentInteractionTracerEvent;
+//# sourceMappingURL=tracerEvents.js.map

package/dist/tracer/tracerEvents.js.map

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

package/dist/tracer/tracerSystem.d.ts

@@ -0,0 +1,149 @@
+/**
+ * TracerSystem module for coordinating tracer events.
+ *
+ * This provides a central system for recording, filtering, and querying tracer events.
+ */
+import { EventStore, FilterOptions } from './eventStore';
+import { TracerEvent, TracerEventConstructor } from './tracerEvents';
+import { ToolCall } from '../llm/models';
+/**
+ * Central system for capturing and querying tracer events.
+ *
+ * The TracerSystem is responsible for recording events related to LLM calls,
+ * tool usage, and agent interactions, providing a way to trace through the
+ * major events of the system.
+ *
+ * @example
+ * ```typescript
+ * const tracer = new TracerSystem();
+ *
+ * tracer.recordLlmCall('gpt-4', [Message.user('Hello')], 0.7, undefined, 'corr-123');
+ * tracer.recordLlmResponse('gpt-4', 'Hi there!', undefined, 150, 'corr-123');
+ *
+ * const events = tracer.getEvents();
+ * console.log(`Recorded ${events.length} events`);
+ * ```
+ */
+export declare class TracerSystem {
+    private eventStore;
+    private _enabled;
+    /**
+     * Initialize the tracer system.
+     *
+     * @param eventStore - The event store to use for storing events. If not provided, a new EventStore will be created.
+     * @param enabled - Whether the tracer system is enabled. If false, no events will be recorded.
+     */
+    constructor(eventStore?: EventStore, enabled?: boolean);
+    /**
+     * Get whether the tracer system is enabled.
+     */
+    get enabled(): boolean;
+    /**
+     * Record a tracer event in the event store.
+     *
+     * @param event - The tracer event to record
+     */
+    recordEvent(event: TracerEvent): void;
+    /**
+     * Record an LLM call event.
+     *
+     * @param model - The name of the LLM model being called
+     * @param messages - The messages sent to the LLM
+     * @param temperature - The temperature setting for the LLM call
+     * @param tools - The tools available to the LLM, if any
+     * @param correlationId - UUID string that is copied from cause-to-effect for tracing events
+     * @param source - The source of the event
+     */
+    recordLlmCall(model: string, messages: unknown[], temperature?: number, tools?: Record<string, unknown>[], correlationId?: string, source?: string): void;
+    /**
+     * Record an LLM response event.
+     *
+     * @param model - The name of the LLM model that responded
+     * @param content - The content of the LLM response
+     * @param toolCalls - Any tool calls made by the LLM in its response
+     * @param callDurationMs - The duration of the LLM call in milliseconds
+     * @param correlationId - UUID string that is copied from cause-to-effect for tracing events
+     * @param source - The source of the event
+     */
+    recordLlmResponse(model: string, content: string, toolCalls?: ToolCall[], callDurationMs?: number, correlationId?: string, source?: string): void;
+    /**
+     * Record a tool call event.
+     *
+     * @param toolName - The name of the tool being called
+     * @param args - The arguments provided to the tool
+     * @param result - The result returned by the tool
+     * @param caller - The name of the agent or component calling the tool
+     * @param callDurationMs - The duration of the tool call in milliseconds
+     * @param correlationId - UUID string that is copied from cause-to-effect for tracing events
+     * @param source - The source of the event
+     */
+    recordToolCall(toolName: string, args: Record<string, unknown>, result: unknown, caller?: string, callDurationMs?: number, correlationId?: string, source?: string): void;
+    /**
+     * Record an agent interaction event.
+     *
+     * @param fromAgent - The name of the agent sending the event
+     * @param toAgent - The name of the agent receiving the event
+     * @param eventType - The type of event being processed
+     * @param eventId - A unique identifier for the event
+     * @param correlationId - UUID string that is copied from cause-to-effect for tracing events
+     * @param source - The source of the event
+     */
+    recordAgentInteraction(fromAgent: string, toAgent: string, eventType: string, eventId?: string, correlationId?: string, source?: string): void;
+    /**
+     * Get tracer events from the store, optionally filtered.
+     *
+     * This is a convenience wrapper around the EventStore's getEvents method,
+     * specifically for tracer events.
+     *
+     * @param options - Filter options for querying events
+     * @returns Events that match the filter criteria
+     *
+     * @example
+     * ```typescript
+     * // Get all LLM call events
+     * const llmCalls = tracer.getEvents({ eventType: LLMCallTracerEvent });
+     *
+     * // Get events in a time range
+     * const recent = tracer.getEvents({
+     *   startTime: Date.now() - 60000,
+     *   endTime: Date.now()
+     * });
+     *
+     * // Get events with custom filter
+     * const filtered = tracer.getEvents({
+     *   filterFunc: (e) => e.correlationId === 'my-id'
+     * });
+     * ```
+     */
+    getEvents(options?: FilterOptions): TracerEvent[];
+    /**
+     * Get the last N tracer events, optionally filtered by type.
+     *
+     * @param n - Number of events to return
+     * @param eventType - Optional event type to filter by
+     * @returns The last N tracer events that match the filter criteria
+     *
+     * @example
+     * ```typescript
+     * // Get last 10 events
+     * const last10 = tracer.getLastNTracerEvents(10);
+     *
+     * // Get last 5 LLM response events
+     * const last5 = tracer.getLastNTracerEvents(5, LLMResponseTracerEvent);
+     * ```
+     */
+    getLastNTracerEvents(n: number, eventType?: TracerEventConstructor): TracerEvent[];
+    /**
+     * Clear all events from the event store.
+     */
+    clear(): void;
+    /**
+     * Enable the tracer system.
+     */
+    enable(): void;
+    /**
+     * Disable the tracer system.
+     */
+    disable(): void;
+}
+//# sourceMappingURL=tracerSystem.d.ts.map

package/dist/tracer/tracerSystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracerSystem.d.ts","sourceRoot":"","sources":["../../src/tracer/tracerSystem.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,WAAW,EACX,sBAAsB,EAKvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAU;IAE1B;;;;;OAKG;gBACS,UAAU,CAAC,EAAE,UAAU,EAAE,OAAO,GAAE,OAAc;IAK5D;;OAEG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAQrC;;;;;;;;;OASG;IACH,aAAa,CACX,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,OAAO,EAAE,EACnB,WAAW,GAAE,MAAY,EACzB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACjC,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAgBP;;;;;;;;;OASG;IACH,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,QAAQ,EAAE,EACtB,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAgBP;;;;;;;;;;OAUG;IACH,cAAc,CACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,MAAM,EACf,cAAc,CAAC,EAAE,MAAM,EACvB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAiBP;;;;;;;;;OASG;IACH,sBAAsB,CACpB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,IAAI;IAgBP;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,SAAS,CAAC,OAAO,GAAE,aAAkB,GAAG,WAAW,EAAE;IAIrD;;;;;;;;;;;;;;;OAeG;IACH,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,WAAW,EAAE;IAIlF;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,OAAO,IAAI,IAAI;CAGhB"}