agents-library 1.1.0

package/dist/utils/logger.js

@@ -0,0 +1,205 @@
+/**
+ * Unreal Engine-Style Logger Utility
+ * ==================================
+ *
+ * Provides structured logging with Unreal Engine format:
+ * [MODULE_NAME] [HH:MM:SS.mmm] LogLevel: Message
+ *
+ * This logger is shared across all KĀDI agents (template-agent-typescript,
+ * agent-producer, agent-artist, etc.) for consistent log formatting.
+ *
+ * Usage:
+ * ```typescript
+ * import { logger, MODULE_AGENT } from 'agents-library';
+ *
+ * logger.info(MODULE_AGENT, 'Application started');
+ * logger.warn(MODULE_SLACK_BOT, 'Circuit breaker open', { timeout: 5000 });
+ * logger.error(MODULE_AGENT, 'Connection failed', error);
+ * logger.debug(MODULE_TOOLS, 'Tool invocation', { toolName: 'echo' });
+ * ```
+ *
+ * @module logger
+ */
+/**
+ * Module name constants for structured logging
+ * All use kebab-case for consistency with KĀDI naming conventions
+ */
+export const MODULE_AGENT = 'template-agent';
+export const MODULE_SLACK_BOT = 'slack-bot';
+export const MODULE_DISCORD_BOT = 'discord-bot';
+export const MODULE_TASK_HANDLER = 'task-handler';
+export const MODULE_TOOLS = 'tools';
+/**
+ * ANSI Color Codes for Terminal Output
+ *
+ * These color codes are applied only in TTY (interactive terminal) environments.
+ * Non-TTY environments (pipes, redirects, log files) automatically receive plain text.
+ *
+ * Respects the NO_COLOR environment variable (https://no-color.org/)
+ * Set NO_COLOR=1 to disable colors globally.
+ */
+const COLORS = {
+    RESET: '\x1b[0m',
+    CYAN: '\x1b[36m', // Info level
+    YELLOW: '\x1b[33m', // Warning level
+    RED: '\x1b[31m', // Error level
+    GRAY: '\x1b[90m', // Debug level
+    WHITE: '\x1b[37m' // Message text color
+};
+/**
+ * UnrealLogger class for Unreal Engine-style structured logging
+ *
+ * Formats all log output as: [MODULE_NAME] [HH:MM:SS.mmm] LogLevel: Message
+ *
+ * @example
+ * ```typescript
+ * const logger = new UnrealLogger();
+ * logger.info('my-module', 'Initialization complete');
+ * // Output: [my-module] [14:32:45.123] Info: Initialization complete
+ * ```
+ */
+class Logger {
+    /**
+     * Get current timestamp in HH:MM:SS.mmm format
+     *
+     * @returns Formatted timestamp string with millisecond precision
+     */
+    getTimestamp() {
+        const now = new Date();
+        const hours = String(now.getHours()).padStart(2, '0');
+        const minutes = String(now.getMinutes()).padStart(2, '0');
+        const seconds = String(now.getSeconds()).padStart(2, '0');
+        const milliseconds = String(now.getMilliseconds()).padStart(3, '0');
+        return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+    }
+    /**
+     * Determine if colors should be used in log output
+     *
+     * Colors are enabled only when:
+     * 1. stdout is a TTY (interactive terminal)
+     * 2. NO_COLOR environment variable is not set
+     *
+     * This respects the NO_COLOR standard (https://no-color.org/)
+     * which provides a universal way to disable colorized output.
+     *
+     * @returns true if colors should be applied, false for plain text
+     */
+    shouldUseColors() {
+        return process.stdout.isTTY && process.env.NO_COLOR === undefined;
+    }
+    /**
+     * Format log message with module name and timestamp
+     *
+     * @param module - Module name (e.g., 'template-agent', 'slack-bot')
+     * @param level - Log level (Info, Warning, Error, Debug)
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m') - always included
+     * @param color - Optional ANSI color code to apply to module bracket, level indicator, and elapsed time
+     * @returns Formatted log string with selective coloring: <color>[module]<reset> [timestamp] <color>level<reset>: <white>message<reset> <color>elapsedTime<reset>
+     */
+    formatMessage(module, level, message, elapsedTime, color) {
+        const timestamp = this.getTimestamp();
+        if (this.shouldUseColors() && color) {
+            // Apply selective coloring with module name and elapsed time both colored to match level:
+            // <color>[module]<reset> [timestamp] <color>level<reset>: <white>message<reset> <color>elapsedTime<reset>
+            // Module bracket colored to match level (cyan/yellow/red/gray)
+            // Timestamp in terminal default color (no color codes)
+            // Level indicator colored to match level
+            // Message text in WHITE
+            // Elapsed time suffix always colored to match level
+            return `${color}[${module}]${COLORS.RESET} [${timestamp}] ${color}${level}${COLORS.RESET}: ${COLORS.WHITE}${message}${COLORS.RESET} ${color}${elapsedTime}${COLORS.RESET}`;
+        }
+        // Plain text for non-TTY environments
+        return `[${module}] [${timestamp}] ${level}: ${message} ${elapsedTime}`;
+    }
+    /**
+     * Log informational message
+     *
+     * Used for normal operational events (startup, connections, completions)
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log (will be logged on separate line)
+     */
+    info(module, message, elapsedTime, data) {
+        console.log(this.formatMessage(module, 'Info', message, elapsedTime, COLORS.CYAN));
+        if (data) {
+            console.log(data);
+        }
+    }
+    /**
+     * Log warning message
+     *
+     * Used for potentially problematic situations (circuit breaker open, retries, timeouts)
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log
+     */
+    warn(module, message, elapsedTime, data) {
+        console.warn(this.formatMessage(module, 'Warning', message, elapsedTime, COLORS.YELLOW));
+        if (data) {
+            console.warn(data);
+        }
+    }
+    /**
+     * Log error message
+     *
+     * Used for error conditions and exceptions
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param error - Optional error object or error message string
+     * @param data - Optional additional data to log
+     */
+    error(module, message, elapsedTime, error, data) {
+        console.error(this.formatMessage(module, 'Error', message, elapsedTime, COLORS.RED));
+        if (error instanceof Error) {
+            if (error.stack) {
+                console.error(error.stack);
+            }
+            else {
+                console.error(error.message);
+            }
+        }
+        else if (error) {
+            console.error(error);
+        }
+        if (data) {
+            console.error(data);
+        }
+    }
+    /**
+     * Log debug message
+     *
+     * Used for detailed diagnostic information during development
+     *
+     * @param module - Module name
+     * @param message - Log message
+     * @param elapsedTime - Elapsed time suffix (e.g., '+5s', '+3m')
+     * @param data - Optional data to log
+     */
+    debug(module, message, elapsedTime, data) {
+        console.log(this.formatMessage(module, 'Debug', message, elapsedTime, COLORS.GRAY));
+        if (data) {
+            console.log(data);
+        }
+    }
+}
+/**
+ * Singleton logger instance
+ *
+ * Export as singleton to ensure consistent timestamp generation and
+ * single source of truth for logging configuration across all agents.
+ *
+ * @example
+ * ```typescript
+ * import { logger, MODULE_AGENT } from 'agents-library';
+ * logger.info(MODULE_AGENT, 'Application started');
+ * ```
+ */
+export const logger = new Logger();
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAyB,CAAC;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAoB,CAAC;AACrD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAsB,CAAC;AACzD,MAAM,CAAC,MAAM,mBAAmB,GAAG,cAAuB,CAAC;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAG,OAAgB,CAAC;AAE7C;;;;;;;;GAQG;AACH,MAAM,MAAM,GAAG;IACX,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,UAAU,EAAM,aAAa;IACnC,MAAM,EAAE,UAAU,EAAI,gBAAgB;IACtC,GAAG,EAAE,UAAU,EAAO,cAAc;IACpC,IAAI,EAAE,UAAU,EAAM,cAAc;IACpC,KAAK,EAAE,UAAU,CAAK,qBAAqB;CAC9C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,MAAM;IACR;;;;OAIG;IACK,YAAY;QAChB,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC1D,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAC1D,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;QAEpE,OAAO,GAAG,KAAK,IAAI,OAAO,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;IAC5D,CAAC;IAED;;;;;;;;;;;OAWG;IACK,eAAe;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC;IACtE,CAAC;IAED;;;;;;;;;OASG;IACK,aAAa,CAAC,MAAc,EAAE,KAAa,EAAE,OAAe,EAAE,WAAmB,EAAE,KAAc;QACrG,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QAEtC,IAAI,IAAI,CAAC,eAAe,EAAE,IAAI,KAAK,EAAE,CAAC;YAClC,0FAA0F;YAC1F,0GAA0G;YAC1G,+DAA+D;YAC/D,uDAAuD;YACvD,yCAAyC;YACzC,wBAAwB;YACxB,oDAAoD;YACpD,OAAO,GAAG,KAAK,IAAI,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,KAAK,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC,KAAK,IAAI,KAAK,GAAG,WAAW,GAAG,MAAM,CAAC,KAAK,EAAE,CAAC;QAC/K,CAAC;QAED,sCAAsC;QACtC,OAAO,IAAI,MAAM,MAAM,SAAS,KAAK,KAAK,KAAK,OAAO,IAAI,WAAW,EAAE,CAAC;IAC5E,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAc,EAAE,OAAe,EAAE,WAAmB,EAAE,IAAU;QACjE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACnF,IAAI,IAAI,EAAE,CAAC;YACP,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,IAAI,CAAC,MAAc,EAAE,OAAe,EAAE,WAAmB,EAAE,IAAU;QACjE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QACzF,IAAI,IAAI,EAAE,CAAC;YACP,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,CAAC;IACL,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,CAAC,MAAc,EAAE,OAAe,EAAE,WAAmB,EAAE,KAAsB,EAAE,IAAU;QAC1F,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QAErF,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YACzB,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBACd,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC/B,CAAC;iBAAM,CAAC;gBACJ,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YACjC,CAAC;QACL,CAAC;aAAM,IAAI,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACzB,CAAC;QAED,IAAI,IAAI,EAAE,CAAC;YACP,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;IACL,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAc,EAAE,OAAe,EAAE,WAAmB,EAAE,IAAU;QAClE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACpF,IAAI,IAAI,EAAE,CAAC;YACP,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;CACJ;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC"}

package/dist/utils/timer.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Timer Utility for Performance Tracking
+ * =====================================
+ *
+ * Provides named timer tracking with human-readable elapsed time formatting.
+ * Tracks multiple concurrent timers and formats output as: +Nms, +Ns, +Nm
+ *
+ * This timer is shared across all KĀDI agents (template-agent-typescript,
+ * agent-producer, agent-artist, etc.) for consistent performance tracking
+ * and elapsed time display in logs.
+ *
+ * Usage:
+ * ```typescript
+ * import { timer } from 'agents-library';
+ *
+ * // Start a timer
+ * timer.start('main');
+ *
+ * // Later, get elapsed time formatted string
+ * logger.info(MODULE_AGENT, 'Application started', timer.elapsed('main'));
+ * // Output: [template-agent] [14:32:45.123] Info: Application started +150ms
+ *
+ * // Even later, elapsed time shows progression
+ * logger.info(MODULE_AGENT, 'Connected to broker', timer.elapsed('main'));
+ * // Output: [template-agent] [14:32:48.234] Info: Connected to broker +3.1s
+ *
+ * // Start nested timer for operation-specific tracking
+ * timer.start('file-write');
+ * // ... perform file operation ...
+ * logger.info(MODULE_AGENT, 'File written', timer.elapsed('file-write'));
+ *
+ * // Reset timer to zero
+ * timer.reset('main');
+ *
+ * // Stop and remove timer from tracking
+ * timer.stop('main');
+ * ```
+ *
+ * @module timer
+ */
+/**
+ * Timer class for tracking named elapsed times with human-readable formatting.
+ *
+ * Maintains a Map of named timers, each storing a start timestamp.
+ * Provides methods to start, check elapsed time, reset, and stop timers.
+ *
+ * @example
+ * ```typescript
+ * const timer = new Timer();
+ * timer.start('operation');
+ * // ... do work ...
+ * const elapsed = timer.elapsed('operation'); // Returns '+150ms', '+2.4s', etc.
+ * ```
+ */
+declare class Timer {
+    /**
+     * Map of timer names to start timestamps (milliseconds since epoch)
+     *
+     * Each named timer stores the timestamp when it was started.
+     * Elapsed time is calculated as: now - startTime
+     *
+     * @private
+     */
+    private timers;
+    /**
+     * Start a named timer
+     *
+     * If a timer with the same name already exists, it is reset to the current time.
+     * This allows restarting a timer without stopping it first.
+     *
+     * Uses performance.now() for high-resolution timing when available,
+     * falls back to Date.now() for millisecond precision.
+     *
+     * @param name - Unique name for this timer (e.g., 'main', 'file-write', 'api-call')
+     *
+     * @example
+     * ```typescript
+     * timer.start('database-query');
+     * // Timer is now tracking
+     * ```
+     */
+    start(name: string): void;
+    /**
+     * Get elapsed time for a named timer as a human-readable formatted string
+     *
+     * Formats the elapsed time automatically:
+     * - Less than 1 second: '+Nms' (milliseconds)
+     * - 1 second to 59.9 seconds: '+Ns' (seconds with 1 decimal)
+     * - 1 minute or more: '+Nm' (minutes with 1 decimal)
+     *
+     * If the timer doesn't exist, returns '+0ms' as a safe fallback.
+     *
+     * @param name - Name of the timer to check
+     * @returns Formatted elapsed time string (e.g., '+150ms', '+2.4s', '+1.2m')
+     *
+     * @example
+     * ```typescript
+     * timer.start('process');
+     * setTimeout(() => {
+     *   console.log(timer.elapsed('process')); // After 1.5s: '+1.5s'
+     * }, 1500);
+     * ```
+     */
+    elapsed(name: string): string;
+    /**
+     * Reset a named timer to the current time
+     *
+     * This is equivalent to stopping and immediately restarting the timer.
+     * The elapsed time will be zero after reset.
+     *
+     * If the timer doesn't exist, it is created with the current time.
+     *
+     * @param name - Name of the timer to reset
+     *
+     * @example
+     * ```typescript
+     * timer.start('attempt');
+     * // ... some work ...
+     * timer.reset('attempt'); // Restart the timer
+     * // ... more work ...
+     * console.log(timer.elapsed('attempt')); // Only counts time after reset
+     * ```
+     */
+    reset(name: string): void;
+    /**
+     * Stop a named timer and remove it from tracking
+     *
+     * After stopping, calling elapsed() for this timer will return '+0ms'.
+     * To resume tracking, call start() again.
+     *
+     * @param name - Name of the timer to stop
+     *
+     * @example
+     * ```typescript
+     * timer.start('temp-operation');
+     * // ... work ...
+     * timer.stop('temp-operation'); // Stops tracking
+     * console.log(timer.elapsed('temp-operation')); // Returns '+0ms'
+     * ```
+     */
+    stop(name: string): void;
+    /**
+     * Get current time in milliseconds
+     *
+     * Uses performance.now() for high-resolution timing when available
+     * (typical in Node.js 8.5.0+), falls back to Date.now() for millisecond precision.
+     *
+     * @private
+     * @returns Current time in milliseconds since timer epoch started
+     */
+    private getCurrentTime;
+}
+/**
+ * Singleton timer instance
+ *
+ * Export as singleton to ensure:
+ * 1. Single source of truth for all timers across the application
+ * 2. Consistent time reference points for all agents
+ * 3. Ability to track global and operation-specific timers
+ *
+ * This follows the same pattern as logger.ts for consistency.
+ *
+ * @example
+ * ```typescript
+ * import { timer } from 'agents-library';
+ *
+ * timer.start('app');
+ * // ... application runs ...
+ * logger.info(MODULE_AGENT, 'Status', timer.elapsed('app'));
+ * ```
+ */
+export declare const timer: Timer;
+/**
+ * Timer class export for TypeScript type annotations
+ *
+ * Use this type when you need to pass the timer or its type as a parameter.
+ *
+ * @example
+ * ```typescript
+ * function logWithTiming(timerInstance: Timer, name: string) {
+ *   console.log(timerInstance.elapsed(name));
+ * }
+ * ```
+ */
+export type { Timer };
+//# sourceMappingURL=timer.d.ts.map

package/dist/utils/timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.d.ts","sourceRoot":"","sources":["../../src/utils/timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;;;;;;;GAaG;AACH,cAAM,KAAK;IACT;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAkC;IAEhD;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA0B7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKzB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;CAQvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK,OAAc,CAAC;AAEjC;;;;;;;;;;;GAWG;AACH,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/utils/timer.js

@@ -0,0 +1,211 @@
+/**
+ * Timer Utility for Performance Tracking
+ * =====================================
+ *
+ * Provides named timer tracking with human-readable elapsed time formatting.
+ * Tracks multiple concurrent timers and formats output as: +Nms, +Ns, +Nm
+ *
+ * This timer is shared across all KĀDI agents (template-agent-typescript,
+ * agent-producer, agent-artist, etc.) for consistent performance tracking
+ * and elapsed time display in logs.
+ *
+ * Usage:
+ * ```typescript
+ * import { timer } from 'agents-library';
+ *
+ * // Start a timer
+ * timer.start('main');
+ *
+ * // Later, get elapsed time formatted string
+ * logger.info(MODULE_AGENT, 'Application started', timer.elapsed('main'));
+ * // Output: [template-agent] [14:32:45.123] Info: Application started +150ms
+ *
+ * // Even later, elapsed time shows progression
+ * logger.info(MODULE_AGENT, 'Connected to broker', timer.elapsed('main'));
+ * // Output: [template-agent] [14:32:48.234] Info: Connected to broker +3.1s
+ *
+ * // Start nested timer for operation-specific tracking
+ * timer.start('file-write');
+ * // ... perform file operation ...
+ * logger.info(MODULE_AGENT, 'File written', timer.elapsed('file-write'));
+ *
+ * // Reset timer to zero
+ * timer.reset('main');
+ *
+ * // Stop and remove timer from tracking
+ * timer.stop('main');
+ * ```
+ *
+ * @module timer
+ */
+/**
+ * Timer class for tracking named elapsed times with human-readable formatting.
+ *
+ * Maintains a Map of named timers, each storing a start timestamp.
+ * Provides methods to start, check elapsed time, reset, and stop timers.
+ *
+ * @example
+ * ```typescript
+ * const timer = new Timer();
+ * timer.start('operation');
+ * // ... do work ...
+ * const elapsed = timer.elapsed('operation'); // Returns '+150ms', '+2.4s', etc.
+ * ```
+ */
+class Timer {
+    /**
+     * Map of timer names to start timestamps (milliseconds since epoch)
+     *
+     * Each named timer stores the timestamp when it was started.
+     * Elapsed time is calculated as: now - startTime
+     *
+     * @private
+     */
+    timers = new Map();
+    /**
+     * Start a named timer
+     *
+     * If a timer with the same name already exists, it is reset to the current time.
+     * This allows restarting a timer without stopping it first.
+     *
+     * Uses performance.now() for high-resolution timing when available,
+     * falls back to Date.now() for millisecond precision.
+     *
+     * @param name - Unique name for this timer (e.g., 'main', 'file-write', 'api-call')
+     *
+     * @example
+     * ```typescript
+     * timer.start('database-query');
+     * // Timer is now tracking
+     * ```
+     */
+    start(name) {
+        const now = this.getCurrentTime();
+        this.timers.set(name, now);
+    }
+    /**
+     * Get elapsed time for a named timer as a human-readable formatted string
+     *
+     * Formats the elapsed time automatically:
+     * - Less than 1 second: '+Nms' (milliseconds)
+     * - 1 second to 59.9 seconds: '+Ns' (seconds with 1 decimal)
+     * - 1 minute or more: '+Nm' (minutes with 1 decimal)
+     *
+     * If the timer doesn't exist, returns '+0ms' as a safe fallback.
+     *
+     * @param name - Name of the timer to check
+     * @returns Formatted elapsed time string (e.g., '+150ms', '+2.4s', '+1.2m')
+     *
+     * @example
+     * ```typescript
+     * timer.start('process');
+     * setTimeout(() => {
+     *   console.log(timer.elapsed('process')); // After 1.5s: '+1.5s'
+     * }, 1500);
+     * ```
+     */
+    elapsed(name) {
+        const startTime = this.timers.get(name);
+        // Timer doesn't exist - return safe fallback
+        if (startTime === undefined) {
+            return '+0ms';
+        }
+        const now = this.getCurrentTime();
+        const elapsedMs = now - startTime;
+        // Format based on magnitude
+        if (elapsedMs < 1000) {
+            // Less than 1 second: show milliseconds
+            return `+${Math.round(elapsedMs)}ms`;
+        }
+        else if (elapsedMs < 60000) {
+            // Less than 1 minute: show seconds with 1 decimal place
+            const seconds = elapsedMs / 1000;
+            return `+${seconds.toFixed(1)}s`;
+        }
+        else {
+            // 1 minute or more: show minutes with 1 decimal place
+            const minutes = elapsedMs / 60000;
+            return `+${minutes.toFixed(1)}m`;
+        }
+    }
+    /**
+     * Reset a named timer to the current time
+     *
+     * This is equivalent to stopping and immediately restarting the timer.
+     * The elapsed time will be zero after reset.
+     *
+     * If the timer doesn't exist, it is created with the current time.
+     *
+     * @param name - Name of the timer to reset
+     *
+     * @example
+     * ```typescript
+     * timer.start('attempt');
+     * // ... some work ...
+     * timer.reset('attempt'); // Restart the timer
+     * // ... more work ...
+     * console.log(timer.elapsed('attempt')); // Only counts time after reset
+     * ```
+     */
+    reset(name) {
+        const now = this.getCurrentTime();
+        this.timers.set(name, now);
+    }
+    /**
+     * Stop a named timer and remove it from tracking
+     *
+     * After stopping, calling elapsed() for this timer will return '+0ms'.
+     * To resume tracking, call start() again.
+     *
+     * @param name - Name of the timer to stop
+     *
+     * @example
+     * ```typescript
+     * timer.start('temp-operation');
+     * // ... work ...
+     * timer.stop('temp-operation'); // Stops tracking
+     * console.log(timer.elapsed('temp-operation')); // Returns '+0ms'
+     * ```
+     */
+    stop(name) {
+        this.timers.delete(name);
+    }
+    /**
+     * Get current time in milliseconds
+     *
+     * Uses performance.now() for high-resolution timing when available
+     * (typical in Node.js 8.5.0+), falls back to Date.now() for millisecond precision.
+     *
+     * @private
+     * @returns Current time in milliseconds since timer epoch started
+     */
+    getCurrentTime() {
+        // Try to use performance.now() for higher resolution timing
+        if (typeof performance !== 'undefined' && performance.now) {
+            return performance.now();
+        }
+        // Fallback to Date.now() for millisecond precision
+        return Date.now();
+    }
+}
+/**
+ * Singleton timer instance
+ *
+ * Export as singleton to ensure:
+ * 1. Single source of truth for all timers across the application
+ * 2. Consistent time reference points for all agents
+ * 3. Ability to track global and operation-specific timers
+ *
+ * This follows the same pattern as logger.ts for consistency.
+ *
+ * @example
+ * ```typescript
+ * import { timer } from 'agents-library';
+ *
+ * timer.start('app');
+ * // ... application runs ...
+ * logger.info(MODULE_AGENT, 'Status', timer.elapsed('app'));
+ * ```
+ */
+export const timer = new Timer();
+//# sourceMappingURL=timer.js.map

package/dist/utils/timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timer.js","sourceRoot":"","sources":["../../src/utils/timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,KAAK;IACT;;;;;;;OAOG;IACK,MAAM,GAAwB,IAAI,GAAG,EAAE,CAAC;IAEhD;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,IAAY;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,IAAY;QAClB,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAExC,6CAA6C;QAC7C,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAClC,MAAM,SAAS,GAAG,GAAG,GAAG,SAAS,CAAC;QAElC,4BAA4B;QAC5B,IAAI,SAAS,GAAG,IAAI,EAAE,CAAC;YACrB,wCAAwC;YACxC,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC;QACvC,CAAC;aAAM,IAAI,SAAS,GAAG,KAAK,EAAE,CAAC;YAC7B,wDAAwD;YACxD,MAAM,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC;YACjC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,sDAAsD;YACtD,MAAM,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC;YAClC,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,IAAY;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,IAAY;QACf,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED;;;;;;;;OAQG;IACK,cAAc;QACpB,4DAA4D;QAC5D,IAAI,OAAO,WAAW,KAAK,WAAW,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC;YAC1D,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC;QAC3B,CAAC;QACD,mDAAmD;QACnD,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC"}