@phnx-labs/agents-cli 1.14.7 → 1.15.0

package/dist/lib/events.js

@@ -3,6 +3,13 @@
  *
  * 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';
@@ -12,6 +19,19 @@ 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();
@@ -36,8 +56,48 @@ function getLogFilePath(date = new Date()) {
 }
 function ensureLogsDir() {
     if (!fs.existsSync(LOGS_DIR)) {
-        fs.mkdirSync(LOGS_DIR, { recursive: true });
+        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 ─────────────────────────────────────────────────────────────────
 /**
@@ -47,6 +107,8 @@ function ensureLogsDir() {
  * @param payload - Event-specific data (agent, version, cwd, etc.)
  */
 export function emit(event, payload = {}) {
+    if (isDisabled())
+        return;
     try {
         ensureLogsDir();
         const record = {
@@ -57,11 +119,20 @@ export function emit(event, payload = {}) {
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
+            ppid: process.ppid,
             event,
-            ...payload,
+            ...truncatePayload(payload),
         };
         const line = JSON.stringify(record) + '\n';
-        fs.appendFileSync(getLogFilePath(), line);
+        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
@@ -88,6 +159,166 @@ export function emitStart(startEvent, payload = {}) {
         });
     };
 }
+// ─── 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.
@@ -140,7 +371,7 @@ export function maybeRotate() {
  * @returns Array of event records
  */
 export function query(options) {
-    const { startDate, endDate = new Date(), eventTypes, agent, limit } = options;
+    const { startDate, endDate = new Date(), eventTypes, agent, command, limit } = options;
     const results = [];
     if (!fs.existsSync(LOGS_DIR))
         return results;
@@ -167,6 +398,8 @@ export function query(options) {
                     continue;
                 if (agent && record.agent !== agent)
                     continue;
+                if (command && record.command !== command)
+                    continue;
                 results.push(record);
                 if (limit && results.length >= limit) {
                     return results;
@@ -179,5 +412,30 @@ export function query(options) {
     }
     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,7 +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 { emitStart, maybeRotate } from './events.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. */
@@ -305,13 +305,17 @@ async function spawnAgent(options) {
     const piped = !process.stdout.isTTY;
     const interactive = options.interactive === true || options.prompt === undefined;
     maybeRotate();
-    const done = emitStart('agent.run.start', {
+    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
@@ -327,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);
         }
@@ -343,23 +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);
-            done({ error: err.message, exitCode: -1 });
+            if (timeoutTimer)
+                clearTimeout(timeoutTimer);
+            timer.end({ error: err.message, exitCode: -1, status: 'error' });
             reject(err);
         });
         child.on('close', (code) => {
-            if (timer)
-                clearTimeout(timer);
-            done({ exitCode: code ?? 0 });
+            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;
+};

package/dist/lib/routines.js

@@ -350,3 +350,71 @@ export function installJobFromSource(sourcePath, name) {
         return { success: false, error: err.message };
     }
 }
+/** List all job names that have run directories. */
+export function listJobsWithRuns() {
+    const runsDir = getRunsDir();
+    if (!fs.existsSync(runsDir))
+        return [];
+    return fs.readdirSync(runsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+}
+/** Count total runs across all jobs. */
+export function countAllRuns() {
+    let total = 0;
+    for (const jobName of listJobsWithRuns()) {
+        total += listRuns(jobName).length;
+    }
+    return total;
+}
+/** Preview runs that would be pruned (keeping only the most recent `keep` per job). */
+export function previewRunsPrune(keep) {
+    const toPrune = [];
+    for (const jobName of listJobsWithRuns()) {
+        const runs = listRuns(jobName);
+        if (runs.length > keep) {
+            const toRemove = runs.slice(0, runs.length - keep);
+            for (const run of toRemove) {
+                toPrune.push({ jobName, runId: run.runId, startedAt: run.startedAt });
+            }
+        }
+    }
+    return toPrune;
+}
+/** Delete old runs, keeping only the most recent `keep` per job. Returns bytes freed and run count. */
+export function pruneRuns(keep) {
+    let deleted = 0;
+    let bytesFreed = 0;
+    for (const jobName of listJobsWithRuns()) {
+        const runs = listRuns(jobName);
+        if (runs.length <= keep)
+            continue;
+        const toRemove = runs.slice(0, runs.length - keep);
+        for (const run of toRemove) {
+            const runDir = getRunDir(jobName, run.runId);
+            bytesFreed += getDirSize(runDir);
+            fs.rmSync(runDir, { recursive: true, force: true });
+            deleted++;
+        }
+    }
+    return { deleted, bytesFreed };
+}
+function getDirSize(dirPath) {
+    if (!fs.existsSync(dirPath))
+        return 0;
+    let size = 0;
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            size += getDirSize(fullPath);
+        }
+        else {
+            try {
+                size += fs.statSync(fullPath).size;
+            }
+            catch { /* ignore */ }
+        }
+    }
+    return size;
+}