@phnx-labs/agents-cli 1.14.6 → 1.15.0

package/dist/lib/events.js

@@ -0,0 +1,441 @@
+/**
+ * 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
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const USER_AGENTS_DIR = path.join(os.homedir(), '.agents');
+const LOGS_DIR = path.join(USER_AGENTS_DIR, 'logs');
+/** Default retention period in days. */
+const DEFAULT_RETENTION_DAYS = 30;
+/** Default max length for truncated strings. */
+const DEFAULT_TRUNCATE_LENGTH = 500;
+/** Environment variable to disable event logging. */
+const DISABLE_ENV_VAR = 'AGENTS_DISABLE_EVENT_LOG';
+/** Check if audit logging is disabled via environment variable. */
+function isDisabled() {
+    const val = process.env[DISABLE_ENV_VAR];
+    return val === '1' || val === 'true';
+}
+/** Directory permissions (owner read/write/execute only). */
+const DIR_MODE = 0o700;
+/** File permissions (owner read/write only). */
+const FILE_MODE = 0o600;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function getTimezoneOffset() {
+    const offset = new Date().getTimezoneOffset();
+    const sign = offset <= 0 ? '+' : '-';
+    const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+    const mins = String(Math.abs(offset) % 60).padStart(2, '0');
+    return `${sign}${hours}:${mins}`;
+}
+function getTimezoneName() {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+    catch {
+        return 'Unknown';
+    }
+}
+function getLogFilePath(date = new Date()) {
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, '0');
+    const dd = String(date.getDate()).padStart(2, '0');
+    return path.join(LOGS_DIR, `events-${yyyy}-${mm}-${dd}.jsonl`);
+}
+function ensureLogsDir() {
+    if (!fs.existsSync(LOGS_DIR)) {
+        fs.mkdirSync(LOGS_DIR, { recursive: true, mode: DIR_MODE });
+    }
+    else {
+        // Ensure permissions are correct on existing dir
+        try {
+            fs.chmodSync(LOGS_DIR, DIR_MODE);
+        }
+        catch {
+            // May fail if not owner
+        }
+    }
+}
+// ─── Truncation ───────────────────────────────────────────────────────────────
+/**
+ * Truncate a string to maxLength, adding ellipsis if truncated.
+ * Returns undefined for null/undefined input.
+ */
+export function truncate(str, maxLength = DEFAULT_TRUNCATE_LENGTH) {
+    if (str == null)
+        return undefined;
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Truncate all string values in a payload object.
+ */
+function truncatePayload(payload, maxLength = DEFAULT_TRUNCATE_LENGTH) {
+    const result = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (typeof value === 'string') {
+            result[key] = truncate(value, maxLength);
+        }
+        else if (Array.isArray(value)) {
+            // Truncate array to first 10 items, truncate each string item
+            result[key] = value.slice(0, 10).map(v => typeof v === 'string' ? truncate(v, maxLength) : v);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+// ─── Core API ─────────────────────────────────────────────────────────────────
+/**
+ * Emit a structured event to the daily log file.
+ *
+ * @param event - The event type
+ * @param payload - Event-specific data (agent, version, cwd, etc.)
+ */
+export function emit(event, payload = {}) {
+    if (isDisabled())
+        return;
+    try {
+        ensureLogsDir();
+        const record = {
+            ts: new Date().toISOString(),
+            tz: getTimezoneOffset(),
+            tzName: getTimezoneName(),
+            hostname: os.hostname(),
+            platform: os.platform(),
+            arch: os.arch(),
+            pid: process.pid,
+            ppid: process.ppid,
+            event,
+            ...truncatePayload(payload),
+        };
+        const line = JSON.stringify(record) + '\n';
+        const logPath = getLogFilePath();
+        fs.appendFileSync(logPath, line, { mode: FILE_MODE });
+        // Ensure file permissions (appendFileSync doesn't respect mode on existing files)
+        try {
+            fs.chmodSync(logPath, FILE_MODE);
+        }
+        catch {
+            // May fail if not owner
+        }
+    }
+    catch {
+        // Silent failure - logging should never break the CLI
+    }
+}
+/**
+ * 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 function emitStart(startEvent, payload = {}) {
+    const startTime = Date.now();
+    emit(startEvent, payload);
+    const endEvent = startEvent.replace('.start', '.end');
+    return (endPayload = {}) => {
+        emit(endEvent, {
+            ...payload,
+            ...endPayload,
+            durationMs: Date.now() - startTime,
+        });
+    };
+}
+// ─── Timing Utilities ─────────────────────────────────────────────────────────
+/**
+ * Measure execution time of a synchronous function.
+ * Emits a perf.timing event with the duration.
+ *
+ * @example
+ * const result = time('parse-config', () => parseConfig(path));
+ */
+export function time(label, fn, payload = {}) {
+    const start = Date.now();
+    try {
+        const result = fn();
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'success',
+        });
+        return result;
+    }
+    catch (err) {
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * 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 async function timeAsync(label, fn, payload = {}) {
+    const start = Date.now();
+    try {
+        const result = await fn();
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'success',
+        });
+        return result;
+    }
+    catch (err) {
+        emit('perf.timing', {
+            ...payload,
+            label,
+            durationMs: Date.now() - start,
+            status: 'error',
+            error: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+}
+/**
+ * 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 function createTimer(label, payload = {}) {
+    const start = Date.now();
+    const marks = {};
+    return {
+        mark(phase) {
+            const elapsed = Date.now() - start;
+            marks[phase] = elapsed;
+            return elapsed;
+        },
+        elapsed() {
+            return Date.now() - start;
+        },
+        end(endPayload = {}) {
+            const durationMs = Date.now() - start;
+            emit('perf.timing', {
+                ...payload,
+                ...endPayload,
+                label,
+                durationMs,
+                phases: marks,
+            });
+        },
+    };
+}
+/**
+ * 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 function withTiming(label, fn, basePayload = {}) {
+    return async (...args) => {
+        const start = Date.now();
+        try {
+            const result = await fn(...args);
+            emit('perf.timing', {
+                ...basePayload,
+                label,
+                durationMs: Date.now() - start,
+                status: 'success',
+            });
+            return result;
+        }
+        catch (err) {
+            emit('perf.timing', {
+                ...basePayload,
+                label,
+                durationMs: Date.now() - start,
+                status: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+    };
+}
+// ─── Command Tracking ─────────────────────────────────────────────────────────
+/**
+ * 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 function emitCommand(command, args = [], payload = {}) {
+    return emitStart('command.start', {
+        ...payload,
+        command,
+        args: args.slice(0, 20), // Limit args to first 20
+        cwd: process.cwd(),
+    });
+}
+// ─── Error Tracking ───────────────────────────────────────────────────────────
+/**
+ * Emit an error event with full details.
+ */
+export function emitError(err, payload = {}) {
+    const error = err instanceof Error ? err : new Error(err);
+    emit('error', {
+        ...payload,
+        error: error.message,
+        errorStack: truncate(error.stack, 1000),
+    });
+}
+// ─── Rotation ─────────────────────────────────────────────────────────────────
+/**
+ * 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 function rotate(retentionDays = DEFAULT_RETENTION_DAYS) {
+    try {
+        if (!fs.existsSync(LOGS_DIR))
+            return 0;
+        const cutoff = Date.now() - retentionDays * 24 * 60 * 60 * 1000;
+        const files = fs.readdirSync(LOGS_DIR).filter(f => f.startsWith('events-') && f.endsWith('.jsonl'));
+        let removed = 0;
+        for (const file of files) {
+            const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
+            if (!match)
+                continue;
+            const [, yyyy, mm, dd] = match;
+            const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
+            if (fileDate.getTime() < cutoff) {
+                fs.unlinkSync(path.join(LOGS_DIR, file));
+                removed++;
+            }
+        }
+        return removed;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Lazy rotation - runs at most once per day per process.
+ */
+let lastRotationCheck = 0;
+export function maybeRotate() {
+    const now = Date.now();
+    const oneDayMs = 24 * 60 * 60 * 1000;
+    if (now - lastRotationCheck > oneDayMs) {
+        lastRotationCheck = now;
+        rotate();
+    }
+}
+// ─── Query ────────────────────────────────────────────────────────────────────
+/**
+ * Read events from log files within a date range.
+ *
+ * @param options - Query options
+ * @returns Array of event records
+ */
+export function query(options) {
+    const { startDate, endDate = new Date(), eventTypes, agent, command, limit } = options;
+    const results = [];
+    if (!fs.existsSync(LOGS_DIR))
+        return results;
+    const files = fs.readdirSync(LOGS_DIR)
+        .filter(f => f.startsWith('events-') && f.endsWith('.jsonl'))
+        .sort()
+        .reverse();
+    for (const file of files) {
+        const match = file.match(/^events-(\d{4})-(\d{2})-(\d{2})\.jsonl$/);
+        if (!match)
+            continue;
+        const [, yyyy, mm, dd] = match;
+        const fileDate = new Date(parseInt(yyyy), parseInt(mm) - 1, parseInt(dd));
+        if (startDate && fileDate < startDate)
+            continue;
+        if (endDate && fileDate > endDate)
+            continue;
+        const content = fs.readFileSync(path.join(LOGS_DIR, file), 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        for (const line of lines.reverse()) {
+            try {
+                const record = JSON.parse(line);
+                if (eventTypes && !eventTypes.includes(record.event))
+                    continue;
+                if (agent && record.agent !== agent)
+                    continue;
+                if (command && record.command !== command)
+                    continue;
+                results.push(record);
+                if (limit && results.length >= limit) {
+                    return results;
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return results;
+}
+// ─── Stats ────────────────────────────────────────────────────────────────────
+/**
+ * Get performance stats for a specific label.
+ */
+export function getTimingStats(label, options = {}) {
+    const days = options.days ?? 7;
+    const startDate = new Date();
+    startDate.setDate(startDate.getDate() - days);
+    const events = query({
+        startDate,
+        eventTypes: ['perf.timing'],
+    }).filter(e => e.label === label && typeof e.durationMs === 'number');
+    if (events.length === 0)
+        return null;
+    const durations = events.map(e => e.durationMs).sort((a, b) => a - b);
+    const sum = durations.reduce((a, b) => a + b, 0);
+    return {
+        count: durations.length,
+        avgMs: Math.round(sum / durations.length),
+        minMs: durations[0],
+        maxMs: durations[durations.length - 1],
+        p50Ms: durations[Math.floor(durations.length * 0.5)],
+        p95Ms: durations[Math.floor(durations.length * 0.95)],
+    };
+}
+// ─── Exports ──────────────────────────────────────────────────────────────────
+export const LOGS_PATH = LOGS_DIR;

package/dist/lib/exec.js

@@ -10,6 +10,7 @@ import * as path from 'path';
 import { parseTimeout } from './routines.js';
 import { getVersionHomePath, isVersionInstalled, resolveVersion } from './versions.js';
 import { resolveModel, buildReasoningFlags } from './models.js';
+import { maybeRotate, createTimer, truncate } from './events.js';
 /** Pattern for valid environment variable names (C identifier rules). */
 const EXEC_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Parse a single KEY=VALUE string into a tuple, validating the key name. */
@@ -201,6 +202,11 @@ export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
     const cmd = [...template.base];
     const interactive = options.interactive === true || options.prompt === undefined;
+    // For Codex, 'exec' is the headless subcommand -- drop it for interactive mode
+    // so we run 'codex' (TUI) instead of 'codex exec' (one-shot)
+    if (options.agent === 'codex' && interactive && cmd[1] === 'exec') {
+        cmd.splice(1, 1);
+    }
     // Use versioned alias if a specific version was requested (e.g., claude@2.1.98)
     if (options.version && cmd.length > 0) {
         cmd[0] = `${cmd[0]}@${options.version}`;
@@ -298,6 +304,19 @@ async function spawnAgent(options) {
     const timeoutMs = options.timeout ? parseTimeout(options.timeout) : undefined;
     const piped = !process.stdout.isTTY;
     const interactive = options.interactive === true || options.prompt === undefined;
+    maybeRotate();
+    const timer = createTimer('agent.run', {
+        agent: options.agent,
+        version: options.version,
+        cwd: options.cwd || process.cwd(),
+        mode: options.mode,
+        model: options.model,
+        interactive,
+        sessionId: options.sessionId,
+        prompt: truncate(options.prompt, 200),
+        command: executable,
+        args: args.slice(0, 10),
+    });
     return new Promise((resolve, reject) => {
         // Interactive mode inherits all stdio so the CLI owns the TTY (TUI
         // rendering, raw-mode keystrokes, colored output). Headless mode pipes
@@ -312,6 +331,8 @@ async function spawnAgent(options) {
             env: buildExecEnv(options),
             shell: false,
         });
+        // Mark startup time (time from function call to process spawn)
+        timer.mark('startup');
         if (!interactive && piped && child.stdout) {
             child.stdout.pipe(process.stdout);
         }
@@ -328,21 +349,23 @@ async function spawnAgent(options) {
                 }
             });
         }
-        let timer;
+        let timeoutTimer;
         if (timeoutMs) {
-            timer = setTimeout(() => {
+            timeoutTimer = setTimeout(() => {
                 child.kill('SIGTERM');
                 setTimeout(() => child.kill('SIGKILL'), 5000);
             }, timeoutMs);
         }
         child.on('error', (err) => {
-            if (timer)
-                clearTimeout(timer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            timer.end({ error: err.message, exitCode: -1, status: 'error' });
             reject(err);
         });
         child.on('close', (code) => {
-            if (timer)
-                clearTimeout(timer);
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            timer.end({ exitCode: code ?? 0, status: code === 0 ? 'success' : 'failed' });
             resolve({ exitCode: code ?? 0, stderr: stderrBuffer });
         });
     });

package/dist/lib/permissions.d.ts

@@ -72,21 +72,24 @@ export declare function getActivePermissionSetName(): string | null;
 export declare function buildPermissionsFromGroups(groupNames: string[]): PermissionSet;
 /**
  * List installed permission sets from central storage.
+ * User dir takes precedence; system entries are surfaced when user has no
+ * same-named override.
  */
 export declare function listInstalledPermissions(): InstalledPermission[];
 /**
- * Get a specific permission set by name.
+ * Get a specific permission set by name. Searches user dir first, then system.
  */
 export declare function getPermissionSet(name: string): InstalledPermission | null;
 /**
- * Install a permission set to central storage.
+ * Install a permission set to user-level central storage.
  */
 export declare function installPermissionSet(sourcePath: string, name: string): {
     success: boolean;
     error?: string;
 };
 /**
- * Remove a permission set from central storage.
+ * Remove a permission set from user-level central storage. System-shipped
+ * sets are intentionally not deletable from user commands.
  */
 export declare function removePermissionSet(name: string): {
     success: boolean;

package/dist/lib/permissions.js

@@ -259,55 +259,58 @@ export function buildPermissionsFromGroups(groupNames) {
 }
 /**
  * List installed permission sets from central storage.
+ * User dir takes precedence; system entries are surfaced when user has no
+ * same-named override.
  */
 export function listInstalledPermissions() {
     ensureAgentsDir();
-    const dir = getPermissionsDir();
-    if (!fs.existsSync(dir)) {
-        return [];
-    }
+    const seen = new Set();
     const results = [];
-    try {
-        const entries = fs.readdirSync(dir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isFile())
-                continue;
-            if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
-                continue;
-            const filePath = path.join(dir, entry.name);
-            const set = parsePermissionSet(filePath);
-            if (set) {
-                results.push({
-                    name: set.name,
-                    path: filePath,
-                    set,
-                });
+    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
+                    continue;
+                const filePath = path.join(dir, entry.name);
+                const set = parsePermissionSet(filePath);
+                if (!set)
+                    continue;
+                if (seen.has(set.name))
+                    continue;
+                seen.add(set.name);
+                results.push({ name: set.name, path: filePath, set });
             }
         }
-    }
-    catch {
-        // Ignore errors
+        catch {
+            // Skip inaccessible directory
+        }
     }
     return results;
 }
 /**
- * Get a specific permission set by name.
+ * Get a specific permission set by name. Searches user dir first, then system.
  */
 export function getPermissionSet(name) {
-    const dir = getPermissionsDir();
-    for (const ext of ['.yml', '.yaml']) {
-        const filePath = safeJoin(dir, name + ext);
-        if (fs.existsSync(filePath)) {
-            const set = parsePermissionSet(filePath);
-            if (set) {
-                return { name: set.name, path: filePath, set };
+    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        for (const ext of ['.yml', '.yaml']) {
+            const filePath = safeJoin(dir, name + ext);
+            if (fs.existsSync(filePath)) {
+                const set = parsePermissionSet(filePath);
+                if (set) {
+                    return { name: set.name, path: filePath, set };
+                }
             }
         }
     }
     return null;
 }
 /**
- * Install a permission set to central storage.
+ * Install a permission set to user-level central storage.
  */
 export function installPermissionSet(sourcePath, name) {
     ensurePermissionsDir();
@@ -315,7 +318,7 @@ export function installPermissionSet(sourcePath, name) {
     if (!set) {
         return { success: false, error: 'Invalid permission file' };
     }
-    const targetPath = safeJoin(getPermissionsDir(), name + '.yml');
+    const targetPath = safeJoin(getUserPermissionsDir(), name + '.yml');
     try {
         fs.copyFileSync(sourcePath, targetPath);
         return { success: true };
@@ -325,10 +328,11 @@ export function installPermissionSet(sourcePath, name) {
     }
 }
 /**
- * Remove a permission set from central storage.
+ * Remove a permission set from user-level central storage. System-shipped
+ * sets are intentionally not deletable from user commands.
  */
 export function removePermissionSet(name) {
-    const dir = getPermissionsDir();
+    const dir = getUserPermissionsDir();
     for (const ext of ['.yml', '.yaml']) {
         const filePath = safeJoin(dir, name + ext);
         if (fs.existsSync(filePath)) {

package/dist/lib/routines.d.ts

@@ -96,3 +96,18 @@ export declare function installJobFromSource(sourcePath: string, name: string):
     success: boolean;
     error?: string;
 };
+/** List all job names that have run directories. */
+export declare function listJobsWithRuns(): string[];
+/** Count total runs across all jobs. */
+export declare function countAllRuns(): number;
+/** Preview runs that would be pruned (keeping only the most recent `keep` per job). */
+export declare function previewRunsPrune(keep: number): Array<{
+    jobName: string;
+    runId: string;
+    startedAt: string;
+}>;
+/** Delete old runs, keeping only the most recent `keep` per job. Returns bytes freed and run count. */
+export declare function pruneRuns(keep: number): {
+    deleted: number;
+    bytesFreed: number;
+};