@creatoria/miniapp-mcp 0.1.0

package/dist/core/element-ref.js

@@ -0,0 +1,213 @@
+/**
+ * ElementRef resolver for locating elements in miniProgram pages
+ * Supports multiple location strategies: refId, selector, xpath, index
+ *
+ * Cache Invalidation:
+ * - Element cache is automatically cleared when page navigation is detected
+ * - Cached elements are validated against current page before use
+ * - Stale elements (from different pages) are removed automatically
+ */
+/**
+ * Generate a unique reference ID for caching elements
+ */
+export function generateRefId() {
+    return Math.random().toString(36).slice(2) + Date.now().toString(36);
+}
+/**
+ * Check if page has changed and clear stale element cache
+ * Called before each element resolution to ensure cache validity
+ *
+ * @param state - Session state with element cache
+ * @param currentPagePath - Current page path
+ */
+export function invalidateStaleCacheEntries(state, currentPagePath) {
+    // If page has changed, clear entire cache (safe approach)
+    if (state.currentPagePath && state.currentPagePath !== currentPagePath) {
+        const previousPath = state.currentPagePath;
+        const clearedCount = state.elements.size;
+        state.elements.clear();
+        state.logger?.info('Element cache cleared due to page navigation', {
+            previousPage: previousPath,
+            currentPage: currentPagePath,
+            clearedElements: clearedCount,
+        });
+    }
+    // Update current page path
+    state.currentPagePath = currentPagePath;
+}
+/**
+ * Resolve page object from sessionState
+ * @param state - Session state containing miniProgram instance
+ * @param pagePath - Optional page path. If not provided, uses currentPage
+ * @returns Page object
+ * @throws Error if miniProgram not connected or page not found
+ */
+export async function resolvePage(state, pagePath) {
+    if (!state.miniProgram) {
+        throw new Error('MiniProgram not launched or connected. Call miniprogram_launch or miniprogram_connect first.');
+    }
+    // If no pagePath specified, use current page
+    if (!pagePath) {
+        const currentPage = await state.miniProgram.currentPage();
+        if (!currentPage) {
+            throw new Error('No current page found. Ensure the miniProgram has navigated to a page.');
+        }
+        return currentPage;
+    }
+    // Find page in pageStack by path
+    const pageStack = await state.miniProgram.pageStack();
+    if (!Array.isArray(pageStack) || pageStack.length === 0) {
+        throw new Error('Page stack is empty. Ensure miniProgram has navigated to pages.');
+    }
+    // Normalize pagePath (support both '/path' and 'path')
+    const normalizedPath = pagePath.startsWith('/') ? pagePath.slice(1) : pagePath;
+    const found = pageStack.find((p) => p.path === normalizedPath || p.path === pagePath);
+    if (!found) {
+        const availablePaths = pageStack.map((p) => p.path).join(', ');
+        throw new Error(`Page not found in stack: ${pagePath}. Available pages: ${availablePaths}`);
+    }
+    return found;
+}
+/**
+ * Resolve element using various location strategies
+ * @param state - Session state containing element cache
+ * @param ref - Element reference input with location strategy
+ * @returns Resolved element with page, element object, and optional refId
+ * @throws Error if element not found or invalid reference
+ */
+export async function resolveElement(state, ref) {
+    // Get the page first
+    const page = await resolvePage(state, ref.pagePath);
+    // Get current page path for cache validation
+    const currentPagePath = page.path || (await state.miniProgram?.currentPage())?.path;
+    // Invalidate stale cache entries if page has changed
+    if (currentPagePath) {
+        invalidateStaleCacheEntries(state, currentPagePath);
+    }
+    let element = null;
+    // Strategy 1: Use cached refId
+    if (ref.refId) {
+        const cached = state.elements.get(ref.refId);
+        if (!cached) {
+            const availableRefs = Array.from(state.elements.keys()).join(', ');
+            throw new Error(`Invalid refId: ${ref.refId}. ` +
+                `Available refIds: ${availableRefs || '(none)'}. ` +
+                `The element may have been removed or the page has changed.`);
+        }
+        // Validate that cached element is from current page
+        if (currentPagePath && cached.pagePath !== currentPagePath) {
+            // Remove stale entry
+            state.elements.delete(ref.refId);
+            throw new Error(`Cached element refId ${ref.refId} is stale. ` +
+                `Element was cached on page '${cached.pagePath}' but current page is '${currentPagePath}'. ` +
+                `Please re-query the element on the current page.`);
+        }
+        element = cached.element;
+    }
+    // Strategy 2: Use XPath (requires SDK 0.11.0+)
+    else if (ref.xpath) {
+        const anyPage = page;
+        // Check if xpath is supported
+        if (typeof anyPage.xpath !== 'function' && typeof anyPage.getElementByXpath !== 'function') {
+            throw new Error('XPath is not supported by current miniprogram-automator SDK version. ' +
+                'Please upgrade to SDK 0.11.0 or later, or use selector instead.');
+        }
+        // If index is specified, use getElementsByXpath
+        if (typeof ref.index === 'number') {
+            if (typeof anyPage.getElementsByXpath === 'function') {
+                const elements = await anyPage.getElementsByXpath(ref.xpath);
+                if (!Array.isArray(elements) || elements.length === 0) {
+                    throw new Error(`No elements found with XPath: ${ref.xpath}`);
+                }
+                if (ref.index < 0 || ref.index >= elements.length) {
+                    throw new Error(`Index ${ref.index} out of range. Found ${elements.length} elements with XPath: ${ref.xpath}`);
+                }
+                element = elements[ref.index];
+            }
+            else {
+                throw new Error('getElementsByXpath is not supported. Cannot use index with xpath in this SDK version.');
+            }
+        }
+        else {
+            // Use getElementByXpath or xpath (fallback)
+            if (typeof anyPage.getElementByXpath === 'function') {
+                element = await anyPage.getElementByXpath(ref.xpath);
+            }
+            else if (typeof anyPage.xpath === 'function') {
+                element = await anyPage.xpath(ref.xpath);
+            }
+        }
+        if (!element) {
+            throw new Error(`Element not found with XPath: ${ref.xpath}`);
+        }
+    }
+    // Strategy 3: Use CSS selector
+    else if (ref.selector) {
+        // If index is specified, use $$
+        if (typeof ref.index === 'number') {
+            const elements = await page.$$(ref.selector);
+            if (!Array.isArray(elements) || elements.length === 0) {
+                throw new Error(`No elements found with selector: ${ref.selector}`);
+            }
+            if (ref.index < 0 || ref.index >= elements.length) {
+                throw new Error(`Index ${ref.index} out of range. Found ${elements.length} elements with selector: ${ref.selector}`);
+            }
+            element = elements[ref.index];
+        }
+        else {
+            // Use $ for single element
+            element = await page.$(ref.selector);
+            if (!element) {
+                throw new Error(`Element not found with selector: ${ref.selector}`);
+            }
+        }
+    }
+    // No valid location strategy provided
+    else {
+        throw new Error('Invalid ElementRef: must provide one of: refId, selector, or xpath');
+    }
+    // Cache element if save=true
+    let newRefId;
+    if (ref.save && element) {
+        newRefId = generateRefId();
+        // Store element with page metadata for cache invalidation
+        state.elements.set(newRefId, {
+            element,
+            pagePath: currentPagePath || page.path || 'unknown',
+            cachedAt: new Date(),
+        });
+        state.logger?.info('Element cached with refId', {
+            refId: newRefId,
+            pagePath: currentPagePath || page.path,
+        });
+    }
+    return {
+        page,
+        element,
+        refId: newRefId,
+    };
+}
+/**
+ * Validate ElementRefInput and provide helpful error messages
+ */
+export function validateElementRef(ref) {
+    if (!ref || typeof ref !== 'object') {
+        throw new Error('ElementRef must be an object');
+    }
+    const hasRefId = typeof ref.refId === 'string' && ref.refId.length > 0;
+    const hasSelector = typeof ref.selector === 'string' && ref.selector.length > 0;
+    const hasXpath = typeof ref.xpath === 'string' && ref.xpath.length > 0;
+    if (!hasRefId && !hasSelector && !hasXpath) {
+        throw new Error('ElementRef must provide one of: refId, selector, or xpath');
+    }
+    if (ref.index !== undefined && typeof ref.index !== 'number') {
+        throw new Error('ElementRef.index must be a number');
+    }
+    if (ref.pagePath !== undefined && typeof ref.pagePath !== 'string') {
+        throw new Error('ElementRef.pagePath must be a string');
+    }
+    if (ref.save !== undefined && typeof ref.save !== 'boolean') {
+        throw new Error('ElementRef.save must be a boolean');
+    }
+}
+//# sourceMappingURL=element-ref.js.map

package/dist/core/element-ref.js.map

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

package/dist/core/logger.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Logger implementation for structured logging with file support
+ */
+import type { Logger, LoggerConfig } from '../types.js';
+/**
+ * Console-based logger implementation
+ */
+export declare class ConsoleLogger implements Logger {
+    private sessionId?;
+    private toolName?;
+    private config;
+    private fileWriter?;
+    constructor(sessionId?: string, toolName?: string, config?: LoggerConfig);
+    /**
+     * Merge user config with defaults and validate values (Issue #7)
+     */
+    private mergeConfig;
+    /**
+     * Check if log level should be output
+     */
+    private shouldLog;
+    /**
+     * Create log entry with metadata
+     */
+    private createEntry;
+    /**
+     * Format log entry for console output
+     */
+    private format;
+    info(message: string, context?: Record<string, any>): void;
+    warn(message: string, context?: Record<string, any>): void;
+    error(message: string, context?: Record<string, any>): void;
+    debug(message: string, context?: Record<string, any>): void;
+    /**
+     * Log entry to console and optionally to file
+     */
+    private log;
+    /**
+     * Flush log buffer to file
+     */
+    flush(): Promise<void>;
+    /**
+     * Dispose logger and flush buffer
+     */
+    dispose(): Promise<void>;
+    /**
+     * Create a child logger with specific tool name
+     */
+    child(toolName: string): Logger;
+}
+/**
+ * Create a logger for a session
+ */
+export declare function createLogger(sessionId: string, config?: LoggerConfig): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/core/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/core/logger.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAsB,YAAY,EAAE,MAAM,aAAa,CAAA;AA8P3E;;GAEG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,OAAO,CAAC,SAAS,CAAC,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAQ;IACzB,OAAO,CAAC,MAAM,CAAwB;IACtC,OAAO,CAAC,UAAU,CAAC,CAAY;gBAEnB,SAAS,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY;IAgBxE;;OAEG;IACH,OAAO,CAAC,WAAW;IA2CnB;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,WAAW;IAWnB;;OAEG;IACH,OAAO,CAAC,MAAM;IAUd,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAM1D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAM1D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAM3D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAM3D;;OAEG;IACH,OAAO,CAAC,GAAG;IAQX;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B;;OAEG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAGhC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAE7E"}

package/dist/core/logger.js

@@ -0,0 +1,378 @@
+/**
+ * Logger implementation for structured logging with file support
+ */
+import { open, mkdir, rename } from 'fs/promises';
+import { statfs } from 'fs/promises'; // Issue #6: Disk space check (Node 18+)
+import { join } from 'path';
+/**
+ * Default logger configuration
+ */
+const DEFAULT_LOGGER_CONFIG = {
+    level: 'info',
+    enableFileLog: false,
+    outputDir: '.mcp-artifacts',
+    bufferSize: 100,
+    flushInterval: 5000,
+    enableFailureSnapshot: false,
+};
+/**
+ * Log level priorities for filtering
+ */
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Internal file writer with buffering for async log writing
+ */
+class FileWriter {
+    sessionId;
+    outputDir;
+    bufferSize;
+    flushInterval;
+    buffer = [];
+    flushTimer;
+    fileHandle;
+    disposed = false;
+    filePath;
+    flushInProgress = false; // Issue #2: Prevent concurrent flushes
+    failureCount = 0; // Issue #1: Circuit breaker for persistent failures
+    MAX_FAILURES = 3; // Disable after 3 consecutive failures
+    constructor(sessionId, outputDir, bufferSize, flushInterval) {
+        this.sessionId = sessionId;
+        this.outputDir = outputDir;
+        this.bufferSize = bufferSize;
+        this.flushInterval = flushInterval;
+        this.startFlushTimer();
+    }
+    /**
+     * Add log entry to buffer (non-blocking)
+     */
+    write(entry) {
+        if (this.disposed)
+            return;
+        this.buffer.push(entry);
+        // Trigger flush if buffer is full
+        if (this.buffer.length >= this.bufferSize) {
+            // Fire-and-forget flush (non-blocking)
+            void this.flush().catch((err) => {
+                console.error('Failed to flush log buffer:', err);
+            });
+        }
+    }
+    /**
+     * Flush buffer to file
+     */
+    async flush() {
+        // Issue #2: Prevent concurrent flushes
+        if (this.buffer.length === 0 || this.disposed || this.flushInProgress)
+            return;
+        this.flushInProgress = true;
+        try {
+            // Extract buffer entries
+            const entries = this.buffer.splice(0, this.buffer.length);
+            const lines = entries
+                .map((e) => {
+                try {
+                    // Issue #13: Handle circular references
+                    return JSON.stringify(e);
+                }
+                catch (error) {
+                    return JSON.stringify({
+                        ...e,
+                        context: '<Serialization failed: circular reference>',
+                        _serializationError: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            })
+                .join('\n') + '\n';
+            try {
+                // Ensure file handle is open
+                if (!this.fileHandle) {
+                    await this.ensureLogDirectory();
+                    this.filePath = join(this.outputDir, 'logs', `session-${this.sessionId}.log`);
+                    this.fileHandle = await open(this.filePath, 'a');
+                }
+                // Issue #6: Check disk space before writing
+                await this.checkDiskSpace();
+                if (this.disposed)
+                    return; // Disk space check may have disabled logging
+                // Issue #8: Rotate file if too large
+                await this.rotateIfNeeded();
+                // Write to file
+                await this.fileHandle.write(lines);
+                // Issue #1: Reset failure count on success
+                this.failureCount = 0;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error.message : String(error);
+                // Handle disk full error
+                if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOSPC') {
+                    console.error('Disk full, disabling file logging');
+                    // Issue #4: Close file handle before disposing to prevent leak
+                    if (this.fileHandle) {
+                        await this.fileHandle.close().catch(() => { });
+                        this.fileHandle = undefined;
+                    }
+                    this.disposed = true;
+                    return;
+                }
+                console.error('Failed to write logs to file:', err);
+                // Issue #1: Circuit breaker - disable after too many failures
+                this.failureCount++;
+                if (this.failureCount >= this.MAX_FAILURES) {
+                    console.error(`Too many flush failures (${this.failureCount}), disabling file logging`);
+                    // Issue #4: Close file handle before disposing
+                    if (this.fileHandle) {
+                        await this.fileHandle.close().catch(() => { });
+                        this.fileHandle = undefined;
+                    }
+                    this.disposed = true;
+                    return;
+                }
+                // Issue #1: Smart retry with buffer size limit
+                // Only keep the most recent entries to prevent unbounded growth
+                const entriesToKeep = Math.min(entries.length, this.bufferSize - this.buffer.length);
+                if (entriesToKeep > 0) {
+                    // Keep newest entries, drop oldest
+                    this.buffer.unshift(...entries.slice(-entriesToKeep));
+                    if (entriesToKeep < entries.length) {
+                        console.warn(`Dropped ${entries.length - entriesToKeep} old log entries due to buffer limit`);
+                    }
+                }
+                else {
+                    console.warn(`Buffer full, dropped ${entries.length} failed log entries`);
+                }
+            }
+        }
+        finally {
+            this.flushInProgress = false;
+        }
+    }
+    /**
+     * Dispose writer and flush remaining buffer
+     */
+    async dispose() {
+        this.disposed = true;
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+        }
+        await this.flush();
+        if (this.fileHandle) {
+            await this.fileHandle.close();
+            this.fileHandle = undefined;
+        }
+    }
+    /**
+     * Start periodic flush timer
+     */
+    startFlushTimer() {
+        this.flushTimer = setInterval(() => {
+            void this.flush().catch((err) => {
+                console.error('Scheduled flush failed:', err);
+            });
+        }, this.flushInterval);
+    }
+    /**
+     * Ensure log directory exists
+     */
+    async ensureLogDirectory() {
+        const logDir = join(this.outputDir, 'logs');
+        await mkdir(logDir, { recursive: true });
+    }
+    /**
+     * Check disk space and warn/disable if low (Issue #6)
+     */
+    async checkDiskSpace() {
+        if (!this.fileHandle || !this.filePath)
+            return;
+        try {
+            const stats = await statfs(this.outputDir);
+            const freeBytes = BigInt(stats.bsize) * BigInt(stats.bavail);
+            const freeMB = Number(freeBytes / BigInt(1024 * 1024));
+            if (freeMB < 100) {
+                console.warn(`[Logger] Low disk space: ${freeMB.toFixed(2)}MB remaining`);
+            }
+            if (freeMB < 10) {
+                console.error('[Logger] Critical disk space (<10MB), disabling file logging');
+                // Close file handle and dispose
+                await this.fileHandle.close().catch(() => { });
+                this.fileHandle = undefined;
+                this.disposed = true;
+            }
+        }
+        catch (error) {
+            // statfs may not be available on all platforms/Node versions
+            // Silently ignore to avoid breaking on older Node versions
+        }
+    }
+    /**
+     * Rotate log file if it exceeds 10MB (Issue #8)
+     */
+    async rotateIfNeeded() {
+        if (!this.fileHandle || !this.filePath)
+            return;
+        try {
+            const stats = await this.fileHandle.stat();
+            const sizeMB = stats.size / (1024 * 1024);
+            if (sizeMB > 10) {
+                console.warn(`[Logger] Log file exceeds 10MB (${sizeMB.toFixed(2)}MB), rotating...`);
+                // Close current file
+                await this.fileHandle.close();
+                // Rename to timestamped backup
+                const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5); // Remove .xxxZ
+                const rotatedPath = `${this.filePath}.${timestamp}`;
+                await rename(this.filePath, rotatedPath);
+                console.error(`[Logger] Rotated log file to: ${rotatedPath}`);
+                // Reopen new file
+                this.fileHandle = await open(this.filePath, 'a');
+            }
+        }
+        catch (error) {
+            console.error('[Logger] Failed to rotate log file:', error);
+            // Continue with existing file handle
+        }
+    }
+}
+/**
+ * Console-based logger implementation
+ */
+export class ConsoleLogger {
+    sessionId;
+    toolName;
+    config;
+    fileWriter;
+    constructor(sessionId, toolName, config) {
+        this.sessionId = sessionId;
+        this.toolName = toolName;
+        this.config = this.mergeConfig(config);
+        // Initialize file writer if enabled
+        if (this.config.enableFileLog && sessionId) {
+            this.fileWriter = new FileWriter(sessionId, this.config.outputDir, this.config.bufferSize, this.config.flushInterval);
+        }
+    }
+    /**
+     * Merge user config with defaults and validate values (Issue #7)
+     */
+    mergeConfig(userConfig) {
+        // Start with defaults
+        const merged = {
+            ...DEFAULT_LOGGER_CONFIG,
+            ...userConfig,
+        };
+        // Issue #7: Validate and clamp buffer size (10 - 10000)
+        const rawBufferSize = merged.bufferSize;
+        merged.bufferSize = Math.max(10, Math.min(merged.bufferSize, 10000));
+        if (rawBufferSize !== merged.bufferSize) {
+            console.warn(`Logger bufferSize clamped to ${merged.bufferSize} (was ${rawBufferSize}). Valid range: 10-10000`);
+        }
+        // Issue #7: Validate and clamp flush interval (100ms - 60s)
+        const rawFlushInterval = merged.flushInterval;
+        merged.flushInterval = Math.max(100, Math.min(merged.flushInterval, 60000));
+        if (rawFlushInterval !== merged.flushInterval) {
+            console.warn(`Logger flushInterval clamped to ${merged.flushInterval}ms (was ${rawFlushInterval}ms). Valid range: 100-60000ms`);
+        }
+        // Issue #7: Validate log level
+        const validLevels = ['debug', 'info', 'warn', 'error'];
+        if (!validLevels.includes(merged.level)) {
+            console.warn(`Invalid log level "${merged.level}", using default "info". Valid levels: ${validLevels.join(', ')}`);
+            merged.level = 'info';
+        }
+        // Issue #7: Validate outputDir is non-empty string
+        if (typeof merged.outputDir !== 'string' || merged.outputDir.trim() === '') {
+            console.warn(`Invalid outputDir "${merged.outputDir}", using default ".mcp-artifacts"`);
+            merged.outputDir = '.mcp-artifacts';
+        }
+        return merged;
+    }
+    /**
+     * Check if log level should be output
+     */
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[this.config.level];
+    }
+    /**
+     * Create log entry with metadata
+     */
+    createEntry(level, message, context) {
+        return {
+            timestamp: new Date(),
+            level,
+            message,
+            sessionId: this.sessionId,
+            toolName: this.toolName,
+            context,
+        };
+    }
+    /**
+     * Format log entry for console output
+     */
+    format(entry) {
+        const timestamp = entry.timestamp.toISOString();
+        const level = entry.level.toUpperCase().padEnd(5);
+        const sessionInfo = entry.sessionId ? ` [${entry.sessionId}]` : '';
+        const toolInfo = entry.toolName ? ` [${entry.toolName}]` : '';
+        const contextInfo = entry.context ? ` ${JSON.stringify(entry.context)}` : '';
+        return `${timestamp} ${level}${sessionInfo}${toolInfo}: ${entry.message}${contextInfo}`;
+    }
+    info(message, context) {
+        if (!this.shouldLog('info'))
+            return;
+        const entry = this.createEntry('info', message, context);
+        this.log(entry);
+    }
+    warn(message, context) {
+        if (!this.shouldLog('warn'))
+            return;
+        const entry = this.createEntry('warn', message, context);
+        this.log(entry);
+    }
+    error(message, context) {
+        if (!this.shouldLog('error'))
+            return;
+        const entry = this.createEntry('error', message, context);
+        this.log(entry);
+    }
+    debug(message, context) {
+        if (!this.shouldLog('debug'))
+            return;
+        const entry = this.createEntry('debug', message, context);
+        this.log(entry);
+    }
+    /**
+     * Log entry to console and optionally to file
+     */
+    log(entry) {
+        // Console output (always)
+        console.error(this.format(entry));
+        // File output (if enabled)
+        this.fileWriter?.write(entry);
+    }
+    /**
+     * Flush log buffer to file
+     */
+    async flush() {
+        await this.fileWriter?.flush();
+    }
+    /**
+     * Dispose logger and flush buffer
+     */
+    async dispose() {
+        await this.fileWriter?.dispose();
+    }
+    /**
+     * Create a child logger with specific tool name
+     */
+    child(toolName) {
+        return new ConsoleLogger(this.sessionId, toolName, this.config);
+    }
+}
+/**
+ * Create a logger for a session
+ */
+export function createLogger(sessionId, config) {
+    return new ConsoleLogger(sessionId, undefined, config);
+}
+//# sourceMappingURL=logger.js.map