@phnx-labs/agents-cli 1.14.6 → 1.15.0

package/dist/commands/secrets.js

@@ -285,10 +285,19 @@ Examples:
 
   # Delete the whole bundle and purge every keychain item it owned
   agents secrets delete prod
+
+  # Generate a random password (32 chars, all character classes)
+  agents secrets generate
+
+  # Generate a 16-char password, or a PIN, or hex
+  agents secrets generate 16
+  agents secrets generate 8 --pin
+  agents secrets generate 32 --hex
 `);
     registerCommandGroups(cmd, [
         { title: 'Bundle commands', names: ['list', 'view', 'create', 'delete'] },
         { title: 'Secret commands', names: ['add', 'rotate', 'remove', 'import', 'export'] },
+        { title: 'Utilities', names: ['generate'] },
     ]);
     cmd
         .command('list')
@@ -702,4 +711,78 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('generate [length]')
+        .description('Generate a random password')
+        .option('-U, --uppercase', 'Include A-Z (default: on)')
+        .option('-l, --lowercase', 'Include a-z (default: on)')
+        .option('-d, --digits', 'Include 0-9 (default: on)')
+        .option('-s, --symbols', 'Include symbols (default: on)')
+        .option('--no-uppercase', 'Exclude A-Z')
+        .option('--no-lowercase', 'Exclude a-z')
+        .option('--no-digits', 'Exclude 0-9')
+        .option('--no-symbols', 'Exclude symbols')
+        .option('--strong', 'Include all character classes')
+        .option('--pin', 'Digits only (shortcut for -d --no-uppercase --no-lowercase --no-symbols)')
+        .option('--hex', 'Hex characters only (0-9, a-f)')
+        .option('-c, --copy', 'Copy to clipboard (does not print)')
+        .action(async (lengthArg, opts) => {
+        const length = lengthArg ? parseInt(lengthArg, 10) : 32;
+        if (isNaN(length) || length < 1 || length > 1024) {
+            console.error(chalk.red('Length must be a number between 1 and 1024.'));
+            process.exit(1);
+        }
+        const UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+        const LOWER = 'abcdefghijklmnopqrstuvwxyz';
+        const DIGITS = '0123456789';
+        const SYMBOLS = '!@#$%^&*()-_=+[]{}|;:,.<>?';
+        const HEX_LOWER = '0123456789abcdef';
+        let charClasses = [];
+        if (opts.hex) {
+            charClasses = [HEX_LOWER];
+        }
+        else if (opts.pin) {
+            charClasses = [DIGITS];
+        }
+        else {
+            const useUpper = opts.strong || opts.uppercase !== false;
+            const useLower = opts.strong || opts.lowercase !== false;
+            const useDigits = opts.strong || opts.digits !== false;
+            const useSymbols = opts.strong || opts.symbols !== false;
+            if (useUpper)
+                charClasses.push(UPPER);
+            if (useLower)
+                charClasses.push(LOWER);
+            if (useDigits)
+                charClasses.push(DIGITS);
+            if (useSymbols)
+                charClasses.push(SYMBOLS);
+        }
+        if (charClasses.length === 0) {
+            console.error(chalk.red('At least one character class must be enabled.'));
+            process.exit(1);
+        }
+        const randomBytes = crypto.getRandomValues(new Uint32Array(length * 2));
+        let password = '';
+        for (let i = 0; i < length; i++) {
+            const classIndex = randomBytes[i * 2] % charClasses.length;
+            const charClass = charClasses[classIndex];
+            const charIndex = randomBytes[i * 2 + 1] % charClass.length;
+            password += charClass[charIndex];
+        }
+        if (opts.copy) {
+            const { spawn } = await import('child_process');
+            const proc = spawn('pbcopy', [], { stdio: ['pipe', 'inherit', 'inherit'] });
+            proc.stdin.write(password);
+            proc.stdin.end();
+            await new Promise((resolve, reject) => {
+                proc.on('close', (code) => code === 0 ? resolve() : reject(new Error('pbcopy failed')));
+                proc.on('error', reject);
+            });
+            console.log(chalk.green(`Password copied to clipboard (${length} chars)`));
+        }
+        else {
+            console.log(password);
+        }
+    });
 }

package/dist/commands/teams.js

@@ -922,13 +922,12 @@ Name teammates with --name alice to refer to them as 'alice' instead of a UUID.
         .command('status [team]')
         .aliases(['s', 'st', 'check'])
         .description("Check in on a team: who's working, what files they touched, recent commands, last output. Pass --since for efficient delta polling.")
-        .option('-f, --filter <state>', 'Show only teammates in this state: working, completed, failed, stopped, or all (default: all)', 'all')
+        .option('-f, --filter <state>', 'Show only teammates in this state: running, completed, failed, stopped, or all (default: all)', 'all')
         .option('-s, --since <iso>', 'Cursor from a previous status call; only show updates after this timestamp (enables efficient polling)')
         .option('--agent-id <id>', 'Show only this one teammate (by UUID or UUID prefix)')
         .option('--json', 'Output machine-readable JSON')
         .action(async (team, opts) => {
-        // Map friendly 'working' → internal 'running' for filter.
-        const filter = opts.filter === 'working' ? 'running' : opts.filter;
+        const filter = opts.filter;
         const mgr = mkManager();
         // No team given → drop into the picker (TTY) or fail clearly (script).
         if (!team) {

package/dist/commands/usage.js

@@ -8,6 +8,12 @@ export function registerUsageCommand(program) {
     program
         .command('usage [agent]')
         .description('Show rate-limit / quota usage per agent')
+        .addHelpText('after', `
+Examples:
+  agents usage              Show usage for all installed agents
+  agents usage claude       Show usage for Claude only
+  agents usage codex        Show usage for Codex only
+`)
         .action(async (agentFilter) => {
         const filter = agentFilter;
         const targets = filter

package/dist/commands/versions.js

@@ -104,7 +104,7 @@ When to use:
   - Multi-account: install different versions for different accounts (each version has its own auth)
   - Project-specific: lock a version for a repo with --project
 
-Note: The first version you install is NOT set as default automatically. Run 'agents use' to set it.
+Note: The first version you install becomes the default automatically.
 `)
         .action(async (specs, options) => {
         const isProject = options.project;
@@ -220,10 +220,14 @@ Note: The first version you install is NOT set as default automatically. Run 'ag
                             console.log(chalk.green(`  Synced: ${synced.join(', ')}`));
                         }
                     }
-                    // Prompt to set as default
+                    // Set as default: auto-set if no default exists, otherwise prompt
                     const currentDefault = getGlobalDefault(agent);
                     if (currentDefault !== installedVersion) {
-                        if (skipPrompts) {
+                        if (!currentDefault) {
+                            // First install for this agent - auto-set without prompting
+                            await setDefaultVersion(agent, installedVersion);
+                        }
+                        else if (skipPrompts) {
                             await setDefaultVersion(agent, installedVersion);
                         }
                         else {
@@ -238,9 +242,7 @@ Note: The first version you install is NOT set as default automatically. Run 'ag
                                     info,
                                 });
                                 const accountHint = formatAccountHint(info, usage.snapshot);
-                                const message = currentDefault
-                                    ? `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`
-                                    : `Set ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint} as default?`;
+                                const message = `Switch default from ${agentLabel(agentConfig.id)}@${currentDefault} to ${agentLabel(agentConfig.id)}@${installedVersion}${accountHint}?`;
                                 const setAsDefault = await confirm({
                                     message,
                                     default: true,

package/dist/lib/browser/chrome.js

@@ -120,7 +120,7 @@ export async function attachToChrome(port) {
 }
 export function killChrome(pid) {
     try {
-        process.kill(pid, 'SIGTERM');
+        process.kill(pid, 'SIGINT');
     }
     catch {
         // Process already dead

package/dist/lib/browser/drivers/ssh.d.ts

@@ -7,3 +7,4 @@ export interface SSHConnection {
     cleanup: () => void;
 }
 export declare function connectSSH(endpoint: string, profile: BrowserProfile): Promise<SSHConnection>;
+export declare function restartRemoteBrowser(user: string, host: string, browserType: string, port: number, customBinary?: string): Promise<void>;

package/dist/lib/browser/drivers/ssh.js

@@ -9,7 +9,7 @@ export async function connectSSH(endpoint, profile) {
     }
     const user = url.username || process.env.USER || 'root';
     const host = url.hostname;
-    const remotePort = parseInt(url.searchParams.get('port') || '9222', 10);
+    const remotePort = url.port ? parseInt(url.port, 10) : 9222;
     const localPort = allocatePort();
     try {
         await ensureRemoteBrowser(user, host, profile.browser, remotePort, profile.binary);
@@ -17,7 +17,7 @@ export async function connectSSH(endpoint, profile) {
     catch {
         // Browser may already be running, continue
     }
-    const tunnel = await startSSHTunnel(user, host, localPort, remotePort);
+    let tunnel = await startSSHTunnel(user, host, localPort, remotePort);
     try {
         await waitForPort(localPort, 8000);
     }
@@ -133,6 +133,27 @@ async function ensureRemoteBrowser(user, host, browserType, port, customBinary)
         }, 2000);
     });
 }
+export async function restartRemoteBrowser(user, host, browserType, port, customBinary) {
+    // Kill any process using the remote debugging port
+    const killCmd = `lsof -ti :${port} | xargs kill -9 2>/dev/null || true`;
+    await runSSHCommand(user, host, killCmd);
+    await sleep(500);
+    await ensureRemoteBrowser(user, host, browserType, port, customBinary);
+    await sleep(1500);
+}
+function runSSHCommand(user, host, cmd) {
+    return new Promise((resolve) => {
+        const child = spawn('ssh', [`${user}@${host}`, '-o', 'BatchMode=yes', cmd], {
+            stdio: 'ignore',
+        });
+        child.on('close', () => resolve());
+        child.on('error', () => resolve());
+        setTimeout(() => {
+            child.kill();
+            resolve();
+        }, 3000);
+    });
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/lib/browser/ipc.js

@@ -195,6 +195,7 @@ export async function sendIPCRequest(request) {
         if (!fs.existsSync(socketPath)) {
             throw new Error('Failed to start browser daemon');
         }
+        await new Promise((r) => setTimeout(r, 300));
     }
     return new Promise((resolve, reject) => {
         const socket = net.createConnection(socketPath);

package/dist/lib/browser/service.d.ts

@@ -2,6 +2,7 @@ import { type TabInfo, type ProfileStatus } from './types.js';
 import { type RefOpts, type RefNode } from './refs.js';
 export declare class BrowserService {
     private connections;
+    private forkingProfiles;
     start(profileName: string, taskId?: string): Promise<{
         task: string;
         windowTargetId?: string;
@@ -30,6 +31,8 @@ export declare class BrowserService {
     hover(taskId: string, tabId: string, ref: number): Promise<void>;
     status(profileName?: string): Promise<ProfileStatus[]>;
     shutdown(): Promise<void>;
+    private findAvailableFork;
+    private forkElectronProfile;
     private connectProfile;
     private connectEndpoint;
     private enableDomains;

package/dist/lib/browser/service.js

@@ -2,14 +2,16 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { CDPClient, discoverBrowserWsUrl } from './cdp.js';
 import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir } from './profiles.js';
-import { killChrome, getRunningChromeInfo } from './chrome.js';
+import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
 import { connectSSH } from './drivers/ssh.js';
 import { generateTaskId, isValidTaskId, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, typeText, pressKey, focusNode } from './input.js';
+import { emit } from '../events.js';
 export class BrowserService {
     connections = new Map();
+    forkingProfiles = new Set();
     async start(profileName, taskId) {
         const profile = await getProfile(profileName);
         if (!profile) {
@@ -20,7 +22,34 @@ export class BrowserService {
             throw new Error(`Invalid task ID "${finalTaskId}". Must be lowercase alphanumeric with hyphens.`);
         }
         let conn = this.connections.get(profileName);
-        if (!conn) {
+        let effectiveProfileName = profileName;
+        if (conn && conn.electron && conn.tasks.size > 0) {
+            if (this.forkingProfiles.has(profileName)) {
+                while (this.forkingProfiles.has(profileName)) {
+                    await new Promise((r) => setTimeout(r, 50));
+                }
+                const existingFork = this.findAvailableFork(profileName);
+                if (existingFork) {
+                    conn = existingFork.conn;
+                    effectiveProfileName = existingFork.name;
+                }
+                else {
+                    throw new Error(`Fork in progress but no available fork found for "${profileName}"`);
+                }
+            }
+            else {
+                this.forkingProfiles.add(profileName);
+                try {
+                    const { forkName, connection } = await this.forkElectronProfile(profile);
+                    conn = connection;
+                    effectiveProfileName = forkName;
+                }
+                finally {
+                    this.forkingProfiles.delete(profileName);
+                }
+            }
+        }
+        else if (!conn) {
             conn = await this.connectProfile(profile);
             this.connections.set(profileName, conn);
         }
@@ -31,14 +60,15 @@ export class BrowserService {
         const { windowTargetId } = await this.createTaskWindow(conn, finalTaskId);
         const task = {
             id: finalTaskId,
-            profile: profileName,
+            profile: effectiveProfileName,
             windowTargetId,
-            tabIds: [],
+            tabIds: conn.electron && windowTargetId ? [windowTargetId] : [],
             createdAt: Date.now(),
             pid: conn.pid,
         };
         conn.tasks.set(finalTaskId, task);
-        await this.saveTaskState(profileName, conn.tasks);
+        await this.saveTaskState(effectiveProfileName, conn.tasks);
+        emit('browser.launch', { profile: effectiveProfileName, task: finalTaskId, pid: conn.pid });
         return { task: finalTaskId, windowTargetId };
     }
     async stop(taskId) {
@@ -62,6 +92,12 @@ export class BrowserService {
                 }
                 conn.tasks.delete(taskId);
                 await this.saveTaskState(profileName, conn.tasks);
+                emit('browser.close', { profile: profileName, task: taskId });
+                if (conn.forkedFrom && conn.tasks.size === 0) {
+                    conn.cdp.close();
+                    killChrome(conn.pid);
+                    this.connections.delete(profileName);
+                }
                 return { ok: true, profile: profileName };
             }
         }
@@ -256,6 +292,37 @@ export class BrowserService {
         }
         this.connections.clear();
     }
+    findAvailableFork(profileName) {
+        for (const [name, conn] of this.connections) {
+            if (conn.forkedFrom === profileName && conn.tasks.size === 0) {
+                return { name, conn };
+            }
+        }
+        return null;
+    }
+    async forkElectronProfile(profile) {
+        let forkNum = 2;
+        while (this.connections.has(`${profile.name}.${forkNum}`)) {
+            forkNum++;
+        }
+        const forkName = `${profile.name}.${forkNum}`;
+        const port = allocatePort();
+        const { pid, wsUrl } = await launchBrowser(forkName, profile.browser, port, profile.chrome, profile.secrets, profile.binary);
+        const cdp = new CDPClient();
+        await cdp.connect(wsUrl);
+        await this.enableDomains(cdp);
+        const connection = {
+            cdp,
+            port,
+            pid,
+            electron: true,
+            forkedFrom: profile.name,
+            tasks: new Map(),
+            sessionCache: new Map(),
+        };
+        this.connections.set(forkName, connection);
+        return { forkName, connection };
+    }
     async connectProfile(profile) {
         const existingInfo = getRunningChromeInfo(profile.name);
         if (existingInfo) {
@@ -311,6 +378,34 @@ export class BrowserService {
                 sessionCache: new Map(),
             };
         }
+        if (url.protocol === 'wss:' || url.protocol === 'ws:') {
+            const cdp = new CDPClient();
+            await cdp.connect(endpoint);
+            await this.enableDomains(cdp);
+            return {
+                cdp,
+                port: 0,
+                pid: 0,
+                electron: profile.electron,
+                tasks: this.loadTaskState(profile.name),
+                sessionCache: new Map(),
+            };
+        }
+        if (url.protocol === 'http:' || url.protocol === 'https:') {
+            const port = parseInt(url.port || (url.protocol === 'https:' ? '443' : '80'), 10);
+            const wsUrl = await discoverBrowserWsUrl(port, url.hostname);
+            const cdp = new CDPClient();
+            await cdp.connect(wsUrl);
+            await this.enableDomains(cdp);
+            return {
+                cdp,
+                port,
+                pid: 0,
+                electron: profile.electron,
+                tasks: this.loadTaskState(profile.name),
+                sessionCache: new Map(),
+            };
+        }
         return null;
     }
     async enableDomains(cdp) {
@@ -320,7 +415,20 @@ export class BrowserService {
         if (conn.electron) {
             const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
             const pageTarget = targetInfos.find((t) => t.type === 'page');
-            return { windowTargetId: pageTarget?.targetId };
+            if (pageTarget) {
+                return { windowTargetId: pageTarget.targetId };
+            }
+            // No existing page - try to create one (works on some Electron apps)
+            try {
+                const result = (await conn.cdp.send('Target.createTarget', {
+                    url: 'about:blank',
+                    newWindow: true,
+                }));
+                return { windowTargetId: result.targetId };
+            }
+            catch {
+                throw new Error('No page targets found and unable to create new window');
+            }
         }
         const result = (await conn.cdp.send('Target.createTarget', {
             url: 'about:blank',

package/dist/lib/daemon.js

@@ -6,7 +6,7 @@
  * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
-import { spawn, execSync } from 'child_process';
+import { spawn, execSync, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -297,10 +297,10 @@ function startDaemonLocked() {
             }
             fs.writeFileSync(plistPath, generateLaunchdPlist(), 'utf-8');
             try {
-                execSync(`launchctl unload "${plistPath}" 2>/dev/null`, { encoding: 'utf-8' });
+                execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
             }
             catch { /* not loaded, expected */ }
-            execSync(`launchctl load "${plistPath}"`, { encoding: 'utf-8' });
+            execFileSync('launchctl', ['load', plistPath], { encoding: 'utf-8' });
             const pid = waitForPid(3000);
             return { pid, method: 'launchd' };
         }
@@ -358,7 +358,7 @@ export function stopDaemon() {
         const plistPath = getLaunchdPlistPath();
         if (fs.existsSync(plistPath)) {
             try {
-                execSync(`launchctl unload "${plistPath}"`, { encoding: 'utf-8' });
+                execFileSync('launchctl', ['unload', plistPath], { encoding: 'utf-8' });
                 fs.unlinkSync(plistPath);
             }
             catch (err) {

package/dist/lib/events.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Centralized event logging for agents-cli.
+ *
+ * Structured JSONL logs at ~/.agents/logs/events-YYYY-MM-DD.jsonl
+ * with automatic daily rotation and rich metadata for debugging/auditing.
+ *
+ * Features:
+ * - Rich metadata: hostname, platform, arch, pid, timezone
+ * - Timing helpers: measure operation duration automatically
+ * - Truncation: long inputs/outputs are trimmed with ellipsis
+ * - Permissions: logs dir is 0700, files are 0600 (owner-only)
+ * - Performance tracking: withTiming() wrapper for any async function
+ */
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'cloud.dispatch' | 'cloud.complete' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'resource.sync' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'error' | 'warn' | 'info' | 'debug';
+export interface EventMeta {
+    ts: string;
+    tz: string;
+    tzName: string;
+    hostname: string;
+    platform: NodeJS.Platform;
+    arch: string;
+    pid: number;
+    ppid: number;
+    event: EventType;
+}
+export interface EventPayload {
+    agent?: string;
+    version?: string;
+    sessionId?: string;
+    cwd?: string;
+    command?: string;
+    args?: string[];
+    input?: string;
+    output?: string;
+    prompt?: string;
+    durationMs?: number;
+    startupMs?: number;
+    exitCode?: number;
+    status?: string;
+    error?: string;
+    errorStack?: string;
+    [key: string]: unknown;
+}
+export type EventRecord = EventMeta & EventPayload;
+/**
+ * Truncate a string to maxLength, adding ellipsis if truncated.
+ * Returns undefined for null/undefined input.
+ */
+export declare function truncate(str: string | null | undefined, maxLength?: number): string | undefined;
+/**
+ * Emit a structured event to the daily log file.
+ *
+ * @param event - The event type
+ * @param payload - Event-specific data (agent, version, cwd, etc.)
+ */
+export declare function emit(event: EventType, payload?: EventPayload): void;
+/**
+ * Convenience wrapper for timed operations.
+ * Returns a function to call when the operation completes.
+ *
+ * @example
+ * const done = emitStart('agent.run.start', { agent: 'claude' });
+ * // ... do work ...
+ * done({ exitCode: 0 }); // emits agent.run.end with durationMs
+ */
+export declare function emitStart(startEvent: EventType, payload?: EventPayload): (endPayload?: EventPayload) => void;
+/**
+ * Measure execution time of a synchronous function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = time('parse-config', () => parseConfig(path));
+ */
+export declare function time<T>(label: string, fn: () => T, payload?: EventPayload): T;
+/**
+ * Measure execution time of an async function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = await timeAsync('fetch-data', () => fetchData(url));
+ */
+export declare function timeAsync<T>(label: string, fn: () => Promise<T>, payload?: EventPayload): Promise<T>;
+/**
+ * Create a timing context for measuring multiple phases of an operation.
+ * Useful for tracking startup time vs execution time.
+ *
+ * @example
+ * const timer = createTimer('agent.run', { agent: 'claude' });
+ * // ... setup work ...
+ * timer.mark('startup'); // records startup time
+ * // ... main work ...
+ * timer.end({ exitCode: 0 }); // records total time and emits event
+ */
+export declare function createTimer(label: string, payload?: EventPayload): {
+    mark: (phase: string) => number;
+    end: (endPayload?: EventPayload) => void;
+    elapsed: () => number;
+};
+/**
+ * Higher-order function that wraps an async function with timing.
+ * The wrapper emits start/end events automatically.
+ *
+ * @example
+ * const timedFetch = withTiming('fetch', fetchData, { service: 'api' });
+ * const result = await timedFetch(url);
+ */
+export declare function withTiming<Args extends unknown[], R>(label: string, fn: (...args: Args) => Promise<R>, basePayload?: EventPayload): (...args: Args) => Promise<R>;
+/**
+ * Emit a command.start event with CLI args.
+ * Returns a done() function to emit command.end with duration.
+ *
+ * @example
+ * // At CLI entry point:
+ * const done = emitCommand('run', process.argv.slice(2));
+ * // ... execute command ...
+ * done({ exitCode: 0 });
+ */
+export declare function emitCommand(command: string, args?: string[], payload?: EventPayload): (endPayload?: EventPayload) => void;
+/**
+ * Emit an error event with full details.
+ */
+export declare function emitError(err: Error | string, payload?: EventPayload): void;
+/**
+ * Remove log files older than the retention period.
+ * Called lazily on emit or explicitly via CLI.
+ *
+ * @param retentionDays - Number of days to keep (default 30)
+ * @returns Number of files removed
+ */
+export declare function rotate(retentionDays?: number): number;
+export declare function maybeRotate(): void;
+/**
+ * Read events from log files within a date range.
+ *
+ * @param options - Query options
+ * @returns Array of event records
+ */
+export declare function query(options: {
+    startDate?: Date;
+    endDate?: Date;
+    eventTypes?: EventType[];
+    agent?: string;
+    command?: string;
+    limit?: number;
+}): EventRecord[];
+/**
+ * Get performance stats for a specific label.
+ */
+export declare function getTimingStats(label: string, options?: {
+    days?: number;
+}): {
+    count: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    p50Ms: number;
+    p95Ms: number;
+} | null;
+export declare const LOGS_PATH: string;